Metadata-Version: 2.3
Name: fastapi-nacos-extension
Version: 0.1.1
Summary: A production-oriented FastAPI extension for Nacos 2.x service discovery and configuration.
Project-URL: Homepage, https://github.com/pumpkin-nbc/Fastapi-Nacos-Extension
Project-URL: Repository, https://github.com/pumpkin-nbc/Fastapi-Nacos-Extension
Project-URL: Documentation, https://github.com/pumpkin-nbc/Fastapi-Nacos-Extension/tree/master/docs
Project-URL: Issues, https://github.com/pumpkin-nbc/Fastapi-Nacos-Extension/issues
Project-URL: Changelog, https://github.com/pumpkin-nbc/Fastapi-Nacos-Extension/blob/master/CHANGELOG.md
Author-email: Pumpkin <a760329881@gmail.com>
License: Apache-2.0
Keywords: configuration,fastapi,microservices,nacos,service-discovery
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: fastapi<1.0.0,>=0.112.2
Requires-Dist: nacos-sdk-python<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == 'dev'
Requires-Dist: httpx<0.29,>=0.27; extra == 'dev'
Requires-Dist: mypy<1.15,>=1.0; extra == 'dev'
Requires-Dist: pytest-cov<6.0,>=4.0; extra == 'dev'
Requires-Dist: pytest<8.4,>=7.0; extra == 'dev'
Requires-Dist: ruff<0.15,>=0.5; extra == 'dev'
Requires-Dist: tomli<3.0,>=2.0; (python_version < '3.11') and extra == 'dev'
Requires-Dist: twine<6.0,>=5.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: httpx<0.29,>=0.27; extra == 'test'
Requires-Dist: pytest-cov<8.0,>=4.0; extra == 'test'
Requires-Dist: pytest<9.0,>=7.0; extra == 'test'
Requires-Dist: tomli<3.0,>=2.0; (python_version < '3.11') and extra == 'test'
Description-Content-Type: text/markdown

# FastAPI-Nacos-Extension

[中文说明](README.zh-CN.md) · [Documentation](docs/quickstart.md) · [Changelog](CHANGELOG.md)

`fastapi-nacos-extension` 0.1.1 is a typed, production-oriented FastAPI integration for
Nacos 2.x. It provides process-safe service registration, discovery, raw
configuration reads, local health status, bounded shutdown deregistration and
post-fork recovery. Async methods keep SDK work off the ASGI event loop, while
matching `_sync` methods support synchronous callers.

> The distribution name is `fastapi-nacos-extension` and the import package is
> `fastapi_nacos_extension`. This project is unrelated to the existing public
> PyPI distribution named `fastapi-nacos`.

## Compatibility

- Python 3.8 or newer
- FastAPI `>=0.112.2,<1.0.0`; Python 3.8 resolves at most 0.124.4
- `nacos-sdk-python` 2.0.0 through 2.0.11 (`>=2.0.0,<3.0.0`)
- Nacos server 2.3.2

## Installation

From PyPI after the first public release:

```bash
python -m pip install fastapi-nacos-extension
```

From a built wheel:

```bash
python -m pip install ./fastapi_nacos_extension-0.1.1-py3-none-any.whl
```

From a local checkout:

```bash
python -m pip install .
```

## Quick start

```python
from fastapi import FastAPI
from fastapi_nacos_extension import FastAPINacos

app = FastAPI()
nacos = FastAPINacos(
    app,
    {
        "NACOS_SERVER_ADDR": "127.0.0.1:8848",
        "NACOS_SERVICE_NAME": "orders-api",
        "NACOS_SERVICE_IP": "127.0.0.1",
        "NACOS_SERVICE_PORT": 8000,
        "NACOS_AUTO_REGISTER": True,
        "NACOS_HEALTH_CHECK_ENABLED": True,
    },
)


@app.get("/upstream")
async def upstream():
    return await nacos.get_one_healthy_instance(app, "payments-api", strategy="weight")


@app.get("/upstream-sync")
def upstream_sync():
    return nacos.get_one_healthy_instance_sync(app, "payments-api", strategy="weight")


@app.get("/remote-config")
async def remote_config():
    return {"content": await nacos.get_config(app, "orders.yaml")}
```

Run it with `uvicorn app:app --host 0.0.0.0 --port 8000`. Initialization is
local and lazy: no Nacos client is constructed and no network request is made
until application startup or the first explicit operation.

## Public API

All application-scoped operations take an explicit `FastAPI` instance. Choose
the async API in an async context so SDK work runs in a worker thread, or the
corresponding `_sync` API in synchronous code to run it in the calling thread.

```python
FastAPINacos(app=None, config=None)
init_app(app, config=None)
await register_instance(app)
register_instance_sync(app)
await deregister_instance(app)
deregister_instance_sync(app)
await get_client(app)
get_client_sync(app)
get_cached_client(app)
get_config_snapshot(app)
await list_instances(app, service_name, group=None, healthy_only=True,
                     cluster=None, metadata=None)
list_instances_sync(app, service_name, group=None, healthy_only=True,
                    cluster=None, metadata=None)
await get_one_healthy_instance(app, service_name, group=None, strategy=None,
                               cluster=None, metadata=None)
get_one_healthy_instance_sync(app, service_name, group=None, strategy=None,
                              cluster=None, metadata=None)
normalize_instance(instance)
await get_config(app, data_id=None, group=None)
get_config_sync(app, data_id=None, group=None)
get_status(app)
```

`get_status()` is a local-only, side-effect-free 16-field lifecycle snapshot.
When enabled, `GET /health/nacos` exposes a stable seven-field local health
response and never contacts Nacos.

## Design guarantees

- Configuration precedence is defaults, constructor config, then `init_app()` config.
- Each application and PID owns an isolated runtime and defensive config snapshot.
- Repeated initialization by the same extension is idempotent.
- User lifespan handlers are composed with the plugin lifespan.
- Registration is non-blocking and uses a last-command-wins state machine.
- Only one lifecycle worker and one Naming RPC run per application/PID.
- Successful registration identity is cached for exact deregistration.
- Transient transport failures recover at a low frequency; deterministic failures stop.
- Preload/fork workers rebuild locks, client and runtime state in the child process.
- Raw SDK logs are silenced because they can contain credentials or config content.

## Documentation

- [Quick start](docs/quickstart.md)
- [Configuration](docs/configuration.md)
- [API reference](docs/api-reference.md)
- [Registration](docs/service-registration.md)
- [Discovery](docs/service-discovery.md)
- [Configuration center](docs/config-center.md)
- [Health check](docs/health-check.md)
- [Production](docs/production.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Compatibility](docs/compatibility.md)
- [Release process](docs/release.md)

## Development

Use the repository environment and run the complete gate:

```bash
.venv/Scripts/python -m ruff check fastapi_nacos_extension tests examples scripts
.venv/Scripts/python -m mypy fastapi_nacos_extension
.venv/Scripts/python -m pytest
.venv/Scripts/python -m build
.venv/Scripts/python -m twine check dist/*
```

CI additionally verifies every Python minor from 3.8 through 3.14. FastAPI
boundary releases and the latest tested version, 0.141.1, are selected according
to each interpreter's supported range. See the compatibility guide for the
complete matrix.

Integration tests are opt-in and must use a disposable Nacos 2.3.2 instance:

```bash
docker compose -f examples/docker-compose-nacos.yml up -d
NACOS_INTEGRATION=1 .venv/Scripts/python -m pytest -m integration
```

## License and provenance

The repository is licensed under Apache License 2.0. Portions are adapted from
an Apache-2.0-licensed predecessor; see [NOTICE](NOTICE) for attribution and scope.
