{"id":45024715,"url":"https://github.com/fireflyframework/pyfly","last_synced_at":"2026-02-28T23:12:20.161Z","repository":{"id":338505984,"uuid":"1158109325","full_name":"fireflyframework/pyfly","owner":"fireflyframework","description":"The official Python implementation of the Firefly Framework — DI, CQRS, EDA, hexagonal architecture, and more.","archived":false,"fork":false,"pushed_at":"2026-02-15T01:14:14.000Z","size":1529,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-15T04:36:55.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fireflyframework.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-14T20:12:35.000Z","updated_at":"2026-02-15T01:14:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fireflyframework/pyfly","commit_stats":null,"previous_names":["fireflyframework/pyfly"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fireflyframework/pyfly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Fpyfly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Fpyfly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Fpyfly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Fpyfly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fireflyframework","download_url":"https://codeload.github.com/fireflyframework/pyfly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Fpyfly/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29601499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T02:50:40.506Z","status":"ssl_error","status_checked_at":"2026-02-19T02:50:26.316Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-19T03:00:29.988Z","updated_at":"2026-02-28T23:12:20.141Z","avatar_url":"https://github.com/fireflyframework.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/pyfly-logo.png\" alt=\"PyFly Logo\" width=\"600\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe Official Python Implementation of the Firefly Framework\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/fireflyframework/pyfly/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/fireflyframework/pyfly/actions/workflows/ci.yml/badge.svg?branch=main\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fireflyframework\"\u003e\u003cimg src=\"https://img.shields.io/badge/Firefly_Framework-official-ff6600?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyeiIvPjwvc3ZnPg==\" alt=\"Firefly Framework\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.12%2B-blue?logo=python\u0026logoColor=white\" alt=\"Python 3.12+\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-green\" alt=\"License: Apache 2.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/version-0.2.0--M9-yellow\" alt=\"Version: 0.2.0-M10\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/type--checked-mypy%20strict-blue?logo=python\u0026logoColor=white\" alt=\"Type Checked: mypy strict\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/code%20style-ruff-purple?logo=ruff\u0026logoColor=white\" alt=\"Code Style: Ruff\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/async-first-brightgreen\" alt=\"Async First\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eBuild production-grade Python applications with the patterns you trust — dependency injection, CQRS, event-driven architecture, and more — powered by the \u003ca href=\"https://github.com/fireflyframework\"\u003eFirefly Framework\u003c/a\u003e.\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## The Problem\n\nYou've been here before. A new Python microservice needs to ship. Before writing a single line of business logic, you spend the first two weeks making choices:\n\n- Which web framework? (FastAPI, Flask, Starlette, Django...)\n- Which ORM? (SQLAlchemy, Tortoise, Django ORM...)\n- Which message broker? (aiokafka, aio-pika, kombu...)\n- How do you wire dependencies? (dependency-injector, python-inject, manual...)\n- How do you structure the project? (Everyone invents their own layout)\n\nYou assemble a bespoke stack, glue it together, and move on. Six months later, another team builds a second service — and makes entirely different choices. Now you have two codebases with different conventions, different testing strategies, different deployment patterns, and no shared understanding of how things work.\n\n**Python gives you infinite choice. What it doesn't give you is cohesion.**\n\n---\n\n## What is PyFly?\n\nPyFly makes these decisions for you.\n\nIt is a **cohesive, full-stack framework** for building production-grade Python applications — microservices, monoliths, and libraries — where every module is designed to work together seamlessly. Dependency injection, HTTP routing, database access, messaging, caching, security, observability, and more — all integrated, all consistent, all with production-ready defaults from day one.\n\n```python\nfrom pyfly.container import rest_controller, service\nfrom pyfly.web import request_mapping, post_mapping, Body, Valid\n\n@service\nclass OrderService:\n    def __init__(self, repo: OrderRepository, events: EventPublisher) -\u003e None:\n        self._repo = repo\n        self._events = events\n\n    async def place_order(self, order: Order) -\u003e Order:\n        saved = await self._repo.save(order)\n        await self._events.publish(OrderPlaced(order_id=saved.id))\n        return saved\n\n@rest_controller\n@request_mapping(\"/orders\")\nclass OrderController:\n    def __init__(self, service: OrderService) -\u003e None:\n        self._service = service\n\n    @post_mapping(\"\", status_code=201)\n    async def create(self, order: Valid[Body[Order]]) -\u003e Order:\n        return await self._service.place_order(order)\n```\n\nNo boilerplate. No manual wiring. The DI container resolves `OrderRepository` and `EventPublisher` from type hints, validates the request body, and publishes domain events — all out of the box.\n\nPyFly is the **official Python implementation** of the [Firefly Framework](https://github.com/fireflyframework), a battle-tested enterprise platform originally built on Spring Boot for Java (40+ modules in production). PyFly brings the same cohesive programming model to Python 3.12+ — not as a port, but as a **native implementation** reimagined for `async/await`, type hints, protocols, and the full power of modern Python.\n\n### Who is PyFly for?\n\n- **Python developers** who want enterprise-grade patterns without reinventing the wheel for every project\n- **Teams** tired of assembling bespoke stacks and want every service to follow the same conventions\n- **Architects** building polyglot platforms who need consistency across Java and Python services\n- **Anyone migrating from Spring Boot** who wants familiar concepts expressed natively in Python\n\nComing from Spring Boot? See the [Spring Boot Comparison Guide](docs/spring-comparison.md) for a side-by-side concept mapping.\n\n---\n\n## Philosophy\n\nFour principles shape every design decision in PyFly. Together, they answer a single question: *how do you build applications that are easy to start, easy to change, and ready for production from the first commit?*\n\n### Convention Over Configuration\n\nStarting a new project should take seconds, not days. PyFly ships with production-ready defaults for every module — logging formats, connection pool sizes, retry policies, security headers, health endpoints — so a new service works immediately with minimal configuration:\n\n```yaml\n# A complete, production-ready web service:\npyfly:\n  web:\n    port: 8080\n```\n\nWhen you need to customize, you override only what matters. Everything else stays sensible.\n\n### Your Code, Not Ours\n\nYour business logic should never import `sqlalchemy`, `redis`, `aiokafka`, or any other infrastructure library. PyFly enforces this through **hexagonal architecture** — the same ports-and-adapters pattern used across all Firefly Framework modules:\n\n- **Ports** are Python `Protocol` classes that define contracts\n- **Adapters** are concrete implementations that fulfill those contracts\n- Your services depend on ports. The DI container wires the adapters at startup.\n\nThe result: you can swap your database from PostgreSQL to MongoDB, your broker from Kafka to RabbitMQ, or your cache from Redis to in-memory — without touching a single line of business logic.\n\n### Async-Native, Type-Safe\n\nEvery PyFly API is designed for `asyncio` from the ground up — no sync-to-async bridges, no thread pool workarounds. Every public surface has complete type annotations validated by mypy in strict mode. If it compiles, it's consistent.\n\n### Production-Ready from Day One\n\nThe first time you run `pyfly run`, your application already has structured logging with correlation IDs, health check endpoints, Prometheus metrics, OWASP security headers, and graceful shutdown. These aren't features you opt into — they're the baseline.\n\n---\n\n## How It Works\n\n### Dependency Injection\n\nPyFly's DI container resolves dependencies from **type hints** — no XML, no service locators, just decorators and Python annotations. The container scans packages listed in `scan_packages`, discovers all decorated classes, and builds a complete dependency graph at startup.\n\n```python\nfrom pyfly.container import Autowired, service\n\n@service\nclass OrderService:\n    metrics: MetricsCollector = Autowired(required=False)  # field injection\n\n    def __init__(self, repo: OrderRepository, events: EventPublisher) -\u003e None:\n        self._repo = repo      # constructor injection (preferred)\n        self._events = events\n```\n\n**How resolution works:** When the container creates `OrderService`, it inspects the `__init__` type hints, finds `OrderRepository` and `EventPublisher` in the bean registry, resolves them recursively (including *their* dependencies), and injects the fully-initialized instances. After construction, it sets any `Autowired()` fields via `setattr`. The entire graph is resolved before your application handles its first request.\n\n**Stereotypes** mark classes with their architectural role and register them with the container:\n\n| Stereotype | Purpose | Layer |\n|------------|---------|-------|\n| `@component` | Generic managed bean | Any |\n| `@service` | Business logic | Service |\n| `@repository` | Data access | Data |\n| `@controller` | Web controller (template responses) | Web |\n| `@rest_controller` | REST endpoints (JSON) | Web |\n| `@shell_component` | CLI commands (import from `pyfly.shell`) | Shell |\n| `@configuration` + `@bean` | Bean factory methods | Infrastructure |\n\nAll stereotypes default to **singleton scope** (one instance per application). You can override with `@service(scope=Scope.TRANSIENT)` for a new instance on every injection, or `Scope.REQUEST` for one instance per HTTP request.\n\n**Advanced capabilities:** `Optional[T]` resolves to `None` when no bean is registered. `list[T]` collects all implementations of a type. `Qualifier(\"name\")` selects a specific named bean when multiple candidates exist. `@primary` marks the default when there are multiple implementations of the same port. The container detects circular dependencies at startup and reports them clearly rather than deadlocking at runtime.\n\n### Hexagonal Architecture\n\nEvery PyFly module that touches external systems is split into two halves: **ports** and **adapters**. Ports are abstract `Protocol` interfaces that your business logic depends on. Adapters are concrete implementations backed by real libraries. The DI container connects them at startup.\n\nThis separation is not conceptual — it is enforced by package structure:\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                    APPLICATION LAYER                     │\n│                                                          │\n│  Your services, controllers, and domain logic.           │\n│  They depend ONLY on ports.                              │\n│                                                          │\n│    @service                                              │\n│    class OrderService:                                   │\n│        repo: RepositoryPort[Order, int]                  │\n│        events: EventPublisher                            │\n│        cache: CacheAdapter                               │\n│                                                          │\n└────────────────────────────┬─────────────────────────────┘\n                             │ depends on\n┌────────────────────────────┴─────────────────────────────┐\n│                 PORTS  (Python Protocols)                │\n│                                                          │\n│  pyfly.data           RepositoryPort[T, ID]              │\n│  pyfly.messaging      MessageBrokerPort                  │\n│  pyfly.cache          CacheAdapter                       │\n│  pyfly.eda            EventPublisher                     │\n│  pyfly.client         HttpClientPort                     │\n│  pyfly.scheduling     TaskExecutorPort                   │\n│  pyfly.shell          ShellRunnerPort                    │\n│  pyfly.web            WebServerPort                      │\n│                                                          │\n└────────────────────────────┬─────────────────────────────┘\n                             │ implements\n┌────────────────────────────┴─────────────────────────────┐\n│            ADAPTERS  (Concrete Implementations)          │\n│                                                          │\n│  pyfly.data.relational.sqlalchemy                        │\n│  pyfly.data.document.mongodb                             │\n│  pyfly.messaging.adapters.kafka                          │\n│  pyfly.messaging.adapters.rabbitmq                       │\n│  pyfly.cache.adapters.redis                              │\n│  pyfly.eda.adapters.memory                               │\n│  pyfly.client.adapters.httpx_adapter                     │\n│  pyfly.scheduling.adapters.asyncio_executor              │\n│  pyfly.shell.adapters.click_adapter                      │\n│  pyfly.web.adapters.starlette                            │\n│                                                          │\n└──────────────────────────────────────────────────────────┘\n```\n\nThe practical result — swap any adapter without changing a single line of business logic:\n\n```python\n# Your service depends on the port, never on the adapter\n@service\nclass OrderService:\n    def __init__(self, repo: RepositoryPort[Order, int]) -\u003e None:\n        self._repo = repo\n\n    async def place_order(self, cmd: PlaceOrder) -\u003e Order:\n        return await self._repo.save(Order(name=cmd.name))\n\n# The @repository stereotype wires the adapter at startup.\n# Switch from SQL to MongoDB by changing one class declaration:\n\n# SQL:     class OrderRepo(Repository[OrderEntity, int]): ...\n# MongoDB: class OrderRepo(MongoRepository[OrderDoc, str]): ...\n# Custom:  class OrderRepo(DynamoRepository[OrderItem, str]): ...\n#\n# OrderService never changes. Tests never change. Controllers never change.\n```\n\n### Auto-Configuration\n\nPyFly detects installed libraries at startup and wires the right adapters automatically — no manual bean registration needed.\n\nThis works through two complementary mechanisms:\n\n**1. Declarative auto-configuration** — `@configuration` classes guarded by conditions. They act as \"default with override\" factories:\n\n```python\nfrom pyfly.context.conditions import auto_configuration, conditional_on_class, conditional_on_missing_bean\nfrom pyfly.container.bean import bean\n\n@auto_configuration\n@conditional_on_missing_bean(CacheAdapter)    # only if user hasn't registered one\n@conditional_on_class(\"redis.asyncio\")        # only if redis is installed\nclass RedisCacheAutoConfig:\n    @bean\n    def cache(self) -\u003e CacheAdapter:\n        return RedisCacheAdapter(url=self._props.redis.url)\n```\n\nThis bean is created only when (1) no user-provided `CacheAdapter` exists and (2) the `redis` library is installed. If the user registers their own `CacheAdapter` via `@bean`, the auto-configuration is silently skipped.\n\n**2. Decentralized entry-point discovery** — Each subsystem owns its own `@auto_configuration` class, registered as a `pyfly.auto_configuration` entry point in `pyproject.toml`. At startup, `discover_auto_configurations()` uses `importlib.metadata.entry_points(group=\"pyfly.auto_configuration\")` to find and load them — no hardcoded imports, no central engine:\n\n| Entry Point | Class | Detects | Binds | Fallback |\n|-------------|-------|---------|-------|----------|\n| `web_fastapi` | `FastAPIAutoConfiguration` | `fastapi` | `FastAPIWebAdapter` | none |\n| `web` | `WebAutoConfiguration` | `starlette` | `StarletteWebAdapter` | none |\n| `server_granian` | `GranianServerAutoConfiguration` | `granian` | `GranianServerAdapter` | none |\n| `server_uvicorn` | `UvicornServerAutoConfiguration` | `uvicorn` | `UvicornServerAdapter` | none |\n| `server_hypercorn` | `HypercornServerAutoConfiguration` | `hypercorn` | `HypercornServerAdapter` | none |\n| `event-loop` | `EventLoopAutoConfiguration` | `uvloop` / `winloop` | Event loop policy | `asyncio` |\n| `relational` | `RelationalAutoConfiguration` | `sqlalchemy` | `Repository[T, ID]` | none |\n| `document` | `DocumentAutoConfiguration` | `motor`, `beanie` | `MongoRepository[T, ID]` | none |\n| `messaging` | `MessagingAutoConfiguration` | `aiokafka` / `aio-pika` | `KafkaAdapter` / `RabbitMQAdapter` | `InMemoryMessageBroker` |\n| `cache` | `CacheAutoConfiguration` | `redis.asyncio` | `RedisCacheAdapter` | `InMemoryCache` |\n| `client` | `ClientAutoConfiguration` | `httpx` | `HttpxClientAdapter` | none |\n| `shell` | `ShellAutoConfiguration` | `click` | `ClickShellAdapter` | none |\n| `cqrs` | `CqrsAutoConfiguration` | — | CQRS handlers | none |\n| `admin` | `AdminAutoConfiguration` | — | Admin dashboard | none |\n| `transactional` | `TransactionalEngineAutoConfiguration` | — | Saga/TCC engines | none |\n| `security-jwt` | `JwtAutoConfiguration` | `pyjwt` | `JWTService` | none |\n| `security-password` | `PasswordEncoderAutoConfiguration` | `bcrypt` | `BcryptPasswordEncoder` | none |\n| `scheduling` | `SchedulingAutoConfiguration` | `croniter` | `TaskScheduler` | none |\n| `metrics` | `MetricsAutoConfiguration` | `prometheus_client` | `MetricsRegistry` | none |\n| `tracing` | `TracingAutoConfiguration` | `opentelemetry` | `TracerProvider` | none |\n| `actuator` | `ActuatorAutoConfiguration` | — | `ActuatorRegistry`, `HealthAggregator` | none |\n| `actuator-metrics` | `MetricsActuatorAutoConfiguration` | `prometheus_client` | `MetricsEndpoint`, `PrometheusEndpoint` | none |\n| `aop` | `AopAutoConfiguration` | — | `AspectBeanPostProcessor` | none |\n\nThird-party packages can register their own auto-configurations by adding entries to the same entry-point group — the same extensibility model as Spring Boot's `META-INF/spring.factories`:\n\n```toml\n# In a third-party pyproject.toml:\n[project.entry-points.\"pyfly.auto_configuration\"]\nmy-addon = \"my_package.auto_configuration:MyAutoConfiguration\"\n```\n\n**The practical workflow:** During development, install `uv add \"pyfly[full]\"` (or `pip install pyfly[full]`) and everything auto-wires. In production Docker images, install only the extras you need (e.g., `pyfly[web,data-relational,cache]`) and the discovered auto-configurations bind exactly those adapters. You can always override any auto-configured adapter with explicit `provider` settings in `pyfly.yaml` or by registering your own bean.\n\n---\n\n## Installation\n\n\u003e **Note:** PyFly is distributed exclusively via [GitHub Releases](https://github.com/fireflyframework/pyfly/releases). It is **not** published to PyPI.\n\n### Install from GitHub Release (Recommended)\n\n```bash\n# Install the latest release (uv)\nuv add \"pyfly @ https://github.com/fireflyframework/pyfly/releases/latest/download/pyfly-0.2.0a10-py3-none-any.whl\"\n\n# Install with specific extras\nuv add \"pyfly[web,data-relational,cache] @ https://github.com/fireflyframework/pyfly/releases/latest/download/pyfly-0.2.0a10-py3-none-any.whl\"\n\n# Or with pip\npip install \"pyfly @ https://github.com/fireflyframework/pyfly/releases/latest/download/pyfly-0.2.0a10-py3-none-any.whl\"\n```\n\n### One-Line Install (CLI + Framework)\n\n```bash\n# Via get.pyfly.io\ncurl -fsSL https://get.pyfly.io/ | bash\n\n# Or directly from GitHub\ncurl -fsSL https://raw.githubusercontent.com/fireflyframework/pyfly/main/install.sh | bash\n```\n\nThe installer clones the repo, creates a virtual environment, installs PyFly with all extras, and adds `pyfly` to your PATH. You can customize with environment variables:\n\n```bash\n# Install to a custom directory\nPYFLY_HOME=/opt/pyfly curl -fsSL https://get.pyfly.io/ | bash\n\n# Install with specific extras only\nPYFLY_EXTRAS=web,data-relational,security curl -fsSL https://get.pyfly.io/ | bash\n```\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/fireflyframework/pyfly.git\ncd pyfly\n\n# Run the interactive installer\nbash install.sh\n\n# Or install manually with uv\nuv sync --all-extras --group dev\n\n# Or with pip\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[full]\"\n```\n\n### Verify Installation\n\n```bash\npyfly --version\npyfly doctor\npyfly info\n```\n\n### Create Your First Project\n\n```bash\n# Quick start — create a REST API with all the batteries\npyfly new my-service --archetype web-api\ncd my-service\npyfly run --reload\n\n# Visit http://localhost:8080/health\n```\n\nSee the [Installation Guide](docs/installation.md) for detailed options, Docker examples, and CI/CD setup.\n\n---\n\n## CLI \u0026 Project Scaffolding\n\nThe `pyfly` CLI generates production-ready project structures with DI stereotypes, Docker support, and layered architecture out of the box.\n\n### Archetypes\n\n| Command | What you get |\n|---------|-------------|\n| `pyfly new my-app` | Minimal microservice (`core` archetype) |\n| `pyfly new my-api --archetype web-api` | REST API with controllers, services, repositories |\n| `pyfly new my-api --archetype fastapi-api` | REST API with FastAPI and native OpenAPI |\n| `pyfly new my-site --archetype web` | Server-rendered HTML with Jinja2 templates |\n| `pyfly new my-svc --archetype hexagonal` | Hexagonal architecture with ports \u0026 adapters |\n| `pyfly new my-lib --archetype library` | Reusable library with `py.typed` marker |\n| `pyfly new my-tool --archetype cli` | CLI application with interactive shell and DI |\n\n### Feature Selection\n\nChoose which PyFly extras to include with `--features`:\n\n```bash\n# REST API with database and caching\npyfly new order-service --archetype web-api --features web,data-relational,cache\n```\n\nAvailable features: `web`, `data-relational`, `data-document`, `eda`, `cache`, `client`, `security`, `scheduling`, `observability`, `cqrs`, `shell`\n\n### Interactive Mode\n\nRun `pyfly new` without arguments for a guided experience:\n\n```\n$ pyfly new\n\n  ╭──────────────────────────────────╮\n  │   PyFly Project Generator        │\n  ╰──────────────────────────────────╯\n\n  Step 1 of 4 — Project Details\n  ? Project name: order-service\n  ? Package name: order_service\n\n  Step 2 of 4 — Architecture\n  ? Select archetype: (use arrow keys)\n    ❯ core          Minimal microservice with DI container and config\n      web-api       Full REST API with controller/service/repository layers\n      web           Server-rendered HTML with Jinja2 templates and static assets\n      hexagonal     Clean architecture with domain isolation\n      library       Reusable library with py.typed and packaging best practices\n      cli           Command-line application with interactive shell and DI\n\n  Step 3 of 4 — Features\n  ? Select features: (space to toggle, enter to confirm)\n    ❯ [x] web          HTTP server, REST controllers, OpenAPI docs\n      [ ] data-relational  Data Relational — SQL databases (SQLAlchemy ORM)\n      ...\n\n  Step 4 of 4 — Review \u0026 Create\n  ? Create this project? Yes\n```\n\n### Generated Web API Structure\n\n```\norder-service/\n├── Dockerfile              # Multi-stage production build\n├── README.md               # Project docs with quick start\n├── pyfly.yaml              # Framework configuration\n├── pyproject.toml          # Dependencies based on selected features\n├── .gitignore\n├── .env.example\n├── src/order_service/\n│   ├── __init__.py\n│   ├── app.py              # @pyfly_application entry point\n│   ├── main.py             # ASGI app factory\n│   ├── controllers/\n│   │   ├── __init__.py\n│   │   ├── health_controller.py   # @rest_controller — /health\n│   │   └── todo_controller.py     # @rest_controller — CRUD /todos\n│   ├── services/\n│   │   ├── __init__.py\n│   │   └── todo_service.py        # @service — business logic\n│   ├── models/\n│   │   ├── __init__.py\n│   │   └── todo.py                # Pydantic DTOs\n│   └── repositories/\n│       ├── __init__.py\n│       └── todo_repository.py     # @repository — data access\n└── tests/\n    ├── __init__.py\n    ├── conftest.py\n    └── test_todo_service.py\n```\n\n### Other CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `pyfly run --reload` | Start the application server with auto-reload |\n| `pyfly info` | Show installed framework version and extras |\n| `pyfly doctor` | Diagnose your development environment |\n| `pyfly db init` | Initialize Alembic migration environment |\n| `pyfly db migrate -m \"msg\"` | Auto-generate a database migration |\n| `pyfly db upgrade` | Apply pending migrations |\n| `pyfly license` | Display the Apache 2.0 license |\n| `pyfly sbom` | Software Bill of Materials (table or JSON) |\n\nSee the full [CLI Reference](docs/cli.md) for details.\n\n---\n\n## Modules\n\nPyFly currently implements **27 modules** organized into four layers:\n\n### Foundation Layer\n\n| Module | Description | Firefly Java Equivalent |\n|--------|-------------|------------------------|\n| **Core** | Application bootstrap, lifecycle, banner, configuration | `fireflyframework-starter-core` |\n| **Kernel** | Exception hierarchy, structured error types | `fireflyframework-kernel` |\n| **Container** | Dependency injection, stereotypes, bean factories | Spring DI (built-in) |\n| **Context** | ApplicationContext, events, lifecycle hooks, conditions | Spring ApplicationContext |\n| **Config** | Decentralized auto-configuration via `@auto_configuration` entry points | Spring Auto-Configuration |\n| **Logging** | Structured logging port and adapters | `fireflyframework-observability` |\n\n### Application Layer\n\n| Module | Description | Firefly Java Equivalent |\n|--------|-------------|------------------------|\n| **Web** | HTTP routing, controllers, middleware, OpenAPI (Starlette and FastAPI adapters) | `fireflyframework-web` |\n| **Server** | Pluggable ASGI servers (Granian, Uvicorn, Hypercorn) and event loops (uvloop, asyncio) | Embedded Tomcat/Jetty/Undertow |\n| **Data** | Repository ports, derived queries, pagination, sorting, entity mapping | Spring Data Commons |\n| **Data Relational** | SQLAlchemy adapter — specifications, transactions, custom queries | `fireflyframework-r2dbc` |\n| **Data Document** | MongoDB adapter — Beanie ODM, document repositories | `fireflyframework-mongodb` |\n| **CQRS** | Command/Query segregation with CommandBus/QueryBus, validation, authorization, caching | `fireflyframework-cqrs` |\n| **Validation** | Input validation with Pydantic | `fireflyframework-validators` |\n\n### Infrastructure Layer\n\n| Module | Description | Firefly Java Equivalent |\n|--------|-------------|------------------------|\n| **Security** | JWT, password encoding, authorization | Part of `fireflyframework-starter-application` |\n| **Messaging** | Kafka, RabbitMQ, in-memory broker | `fireflyframework-eda` |\n| **EDA** | Event-driven architecture, event bus | `fireflyframework-eda` |\n| **Cache** | Caching decorators, Redis adapter | `fireflyframework-cache` |\n| **Client** | HTTP client, circuit breaker, retry | `fireflyframework-client` |\n| **Scheduling** | Cron jobs, fixed-rate tasks | Spring Scheduling |\n| **Resilience** | Rate limiter, bulkhead, timeout, fallback | Resilience4j (in `fireflyframework-client`) |\n| **Shell** | CLI commands, interactive REPL, runners | Spring Shell |\n| **Transactional** | Distributed Saga and TCC transaction orchestration with compensation and recovery | `fireflyframework-transactional-engine` |\n\n### Cross-Cutting Layer\n\n| Module | Description | Firefly Java Equivalent |\n|--------|-------------|------------------------|\n| **AOP** | Aspect-oriented programming | Spring AOP |\n| **Observability** | Prometheus metrics, OpenTelemetry tracing | `fireflyframework-observability` |\n| **Actuator** | Health checks, monitoring endpoints | `fireflyframework-starter-core` (actuator) |\n| **Admin** | Embedded management dashboard with 15 views, SSE streams, server mode fleet monitoring | Spring Boot Admin |\n| **Testing** | Test fixtures and assertions | Spring Test |\n| **CLI** | Command-line tools | `fireflyframework-cli` |\n\n---\n\n## Documentation\n\nFull documentation lives in the [`docs/`](docs/README.md) directory:\n\n- [Getting Started Tutorial](docs/getting-started.md) — Build your first PyFly application step by step\n- [Installation](docs/installation.md) — Install and configure PyFly with the right extras\n- [Architecture Overview](docs/architecture.md) — Understand the framework's design and patterns\n- [CLI Reference](docs/cli.md) — Command-line tools (new, run, db, info, doctor, license, sbom)\n- [Spring Boot Comparison](docs/spring-comparison.md) — Side-by-side concept mapping for Java developers\n\n### Module Guides\n\nBrowse all guides in the [Module Guides Index](docs/modules/README.md):\n\n- [Web Layer](docs/modules/web.md) — REST controllers, routing, parameter binding, OpenAPI\n- [Server Layer](docs/modules/server.md) — Pluggable ASGI servers, event loops, auto-configuration\n- [Data Commons](docs/modules/data.md) — Repository ports, derived queries, pagination, sorting, entity mapping\n- [Data Relational (SQL)](docs/modules/data-relational.md) — SQLAlchemy adapter: specifications, transactions, custom queries\n- [Data Document (MongoDB)](docs/modules/data-document.md) — MongoDB adapter: MongoRepository, Beanie ODM patterns\n- [Validation](docs/modules/validation.md) — `Valid[T]` annotation, structured 422 errors\n- [WebFilters](docs/modules/web-filters.md) — Request/response filter chain\n- [Actuator](docs/modules/actuator.md) — Health checks, extensible endpoints\n- [Custom Actuator Endpoints](docs/modules/custom-actuator-endpoints.md) — Build your own actuator endpoints\n- [Transactional Engine](docs/modules/transactional.md) — SAGA and TCC distributed transaction patterns\n- [Admin Dashboard](docs/modules/admin.md) — Embedded management dashboard, server mode, custom views\n\n### Adapter Reference\n\nBrowse the [Adapter Catalog](docs/adapters/README.md) for setup and configuration of each concrete backend:\n\n- [SQLAlchemy](docs/adapters/sqlalchemy.md) · [MongoDB](docs/adapters/mongodb.md) · [Starlette](docs/adapters/starlette.md) · [FastAPI](docs/adapters/fastapi.md) · [Granian](docs/adapters/granian.md) · [Kafka](docs/adapters/kafka.md) · [RabbitMQ](docs/adapters/rabbitmq.md) · [Redis](docs/adapters/redis.md) · [HTTPX](docs/adapters/httpx.md) · [Click](docs/adapters/click.md)\n\nBrowse the full list in the [Documentation Table of Contents](docs/README.md).\n\n---\n\n## Roadmap\n\nSee **[ROADMAP.md](ROADMAP.md)** for the full roadmap toward feature parity with the Firefly Framework Java ecosystem (40+ modules).\n\n| Phase | Focus | Key Modules |\n|-------|-------|-------------|\n| **Phase 1** | Core Distributed Patterns | Event Sourcing, ~~Saga/TCC~~ (done), Workflow, DDD |\n| **Phase 2** | Business Logic | Rule Engine, Plugins, Data Processing |\n| **Phase 3** | Enterprise Integrations | Notifications, IDP, ECM, Webhooks |\n| **Phase 4** | Administrative | Backoffice, Config Server, Utils |\n\n---\n\n## Versioning\n\nPyFly follows the same versioning system as Spring Boot, based on **Semantic Versioning** (`MAJOR.MINOR.PATCH`) with four release stages:\n\n| Stage | Format | Description |\n|-------|--------|-------------|\n| **SNAPSHOT** | `0.2.0-SNAPSHOT` | Active development build. Unstable, changes daily. |\n| **Milestone** | `0.2.0-M10` | Pre-release feature preview. New functionality available for early feedback. |\n| **Release Candidate** | `0.2.0-RC1` | Feature-complete. Only bug fixes from this point. |\n| **GA** | `0.2.0` | General Availability. Production-ready, fully tested and stable. |\n\n**Release lifecycle:** `SNAPSHOT` → `M1` → `M2` → ... → `RC1` → `RC2` → ... → `GA`\n\nFor Python packaging (PEP 440), milestone versions map to alpha pre-releases (`0.2.0a10`), release candidates map to `rc` (`0.2.0rc1`), and GA is the final release (`0.2.0`). See [docs/versioning.md](docs/versioning.md) for full details.\n\n---\n\n## Changelog\n\nSee **[CHANGELOG.md](CHANGELOG.md)** for detailed release notes.\n\n**Current:** 0.2.0-M10 (2026-02-28) — uv-first tooling: PEP 735 dependency-groups, uv-native CI/templates/installer, tool-neutral error messages.\n\n---\n\n## Firefly Framework Ecosystem\n\nPyFly is part of the [Firefly Framework](https://github.com/fireflyframework) ecosystem:\n\n| Platform | Repository | Status |\n|----------|-----------|--------|\n| **Java / Spring Boot** | [`fireflyframework-*`](https://github.com/fireflyframework) (40+ modules) | Production |\n| **Python** | [`pyfly`](https://github.com/fireflyframework/pyfly) | Milestone (M6) |\n| **Frontend (Angular)** | [`flyfront`](https://github.com/fireflyframework/flyfront) | Active Development |\n| **GenAI** | [`fireflyframework-genai`](https://github.com/fireflyframework/fireflyframework-genai) | Active Development |\n| **CLI (Go)** | [`fireflyframework-cli`](https://github.com/fireflyframework/fireflyframework-cli) | Active Development |\n\n---\n\n## Requirements\n\n| Requirement | Version |\n|-------------|---------|\n| Python | \u003e= 3.12 |\n| uv | \u003e= 0.5 recommended (pip also supported) |\n| Git | For cloning the repository |\n| OS | macOS, Linux (Windows support planned) |\n\n---\n\n## License\n\nApache License 2.0 — [Firefly Software Solutions Inc.](https://github.com/fireflyframework)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireflyframework%2Fpyfly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffireflyframework%2Fpyfly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireflyframework%2Fpyfly/lists"}