Pyagenity API

A Python API framework with GraphQL support, task management, and CLI tools for building scalable web applications.

Installation

From PyPI (Recommended)

pip install pyagenity-api

From Source

git clone https://github.com/Iamsdt/pyagenity-api.git
cd pyagenity-api
pip install -e .

Quick Start

1. Initialize a new project:

pag init

2. Start the API server with default configuration:

pag api

3. Start the API server with custom configuration:

pag api --config custom-config.json

4. Start the API server on different host/port:

pag api --host 127.0.0.1 --port 9000

5. Generate a Dockerfile for containerization:

pag build

CLI Commands

The pag command provides the following subcommands:

pag api

Start the Pyagenity API server.

Options:

• --config TEXT: Path to config file (default: pyagenity.json)
• --host TEXT: Host to run the API on (default: 0.0.0.0)
• --port INTEGER: Port to run the API on (default: 8000)
• --reload/--no-reload: Enable auto-reload (default: enabled)

Examples:

# Start with default configuration
pag api

# Start with custom config file
pag api --config my-config.json

# Start on localhost only, port 9000
pag api --host 127.0.0.1 --port 9000

# Start without auto-reload
pag api --no-reload

pag init

Initialize a new config file with default settings.

Options:

• --output TEXT: Output config file path (default: pyagenity.json)
• --force: Overwrite existing config file

Examples:

# Create default config
pag init

# Create config with custom name
pag init --output custom-config.json

# Overwrite existing config
pag init --force

pag version

Show the CLI version information.

pag version

pag build

Generate a Dockerfile for the Pyagenity API application.

Options:

• --output TEXT: Output Dockerfile path (default: Dockerfile)
• --force/--no-force: Overwrite existing Dockerfile (default: no-force)
• --python-version TEXT: Python version to use (default: 3.11)
• --port INTEGER: Port to expose in the container (default: 8000)

Examples:

# Generate default Dockerfile
pag build

# Generate with custom Python version and port
pag build --python-version 3.12 --port 9000

# Overwrite existing Dockerfile
pag build --force

# Generate with custom filename
pag build --output MyDockerfile

Features:

• 🔍 Automatic requirements.txt detection: Searches for requirements files in multiple locations
• ⚠️ Smart fallback: If no requirements.txt found, installs pyagenity-api from PyPI
• 🐳 Production-ready: Generates optimized Dockerfile with security best practices
• 🔧 Customizable: Supports custom Python versions, ports, and output paths
• 🏥 Health checks: Includes built-in health check endpoint
• 👤 Non-root user: Runs container as non-root for security

Configuration

The configuration file (pyagenity.json) supports the following structure:

{
  "app": {
    "name": "Pyagenity API",
    "version": "1.0.0",
    "debug": true
  },
  "server": {
    "host": "0.0.0.0",
    "port": 8000,
    "workers": 1
  },
  "database": {
    "url": "sqlite://./pyagenity.db"
  },
  "redis": {
    "url": "redis://localhost:6379"
  }
}

File Resolution

The CLI automatically finds your config file in this order:

1. Absolute path (if provided with --config)
2. Current working directory
3. Relative to script location (for development)
4. Package installation directory (fallback)

Project Structure

pyagenity-api/
├── pyagenity_api/           # Main package directory
│   ├── __init__.py         # Package initialization
│   ├── cli.py              # CLI module
│   └── src/                # Source code
│       └── app/            # FastAPI application
│           ├── main.py     # FastAPI app entry point
│           ├── core/       # Core functionality
│           ├── routers/    # API routes
│           └── tasks/      # Background tasks
├── graph/                  # Graph implementation
├── migrations/             # Database migrations
├── scripts/               # Utility scripts
├── docs/                  # Documentation
├── pyproject.toml         # Project configuration
├── requirements.txt       # Dependencies
├── Makefile              # Development commands
├── MANIFEST.in           # Package manifest
└── README.md             # This file

Features

• FastAPI Backend: High-performance async web framework
• GraphQL Support: Built-in GraphQL API with Strawberry
• Task Management: Background task processing with Taskiq
• CLI Tools: Command-line interface for easy management
• Database Integration: Support for multiple databases via Tortoise ORM
• Redis Integration: Caching and session management
• Authentication: Firebase authentication support
• Development Tools: Pre-commit hooks, linting, testing
• Docker Support: Container deployment ready

Setup

Prerequisites

• Python 3.x
• pip
• [Any other prerequisites]

Installation

1. Clone the repository:

   git clone https://github.com/10XScale-in/backend-base.git
   

2. Create a virtual environment and activate:

   python -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

Database

Database Configuration

The database configuration is located in src/app/db/setup_database.py.

Database Migration

We use Aerich for database migrations. Follow these steps to manage your database:

1. Initialize the database initially:

   aerich init -t src.app.db.setup_database.TORTOISE_ORM
   

2. Create initial database schema:

   aerich init-db
   

3. Generate migration files:

   aerich migrate
   

4. Apply migrations:

   aerich upgrade
   

5. Revert migrations (if needed):

   aerich downgrade
   

Running the Application

Command Line

To run the FastAPI application using Uvicorn:

1. Start the application:

   uvicorn src.app.main:app --reload
   

2. You can also run the debugger.

VS Code

Add the following configuration to your .vscode/launch.json file:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: FastAPI",
            "type": "python",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "src.app.main:app",
                "--host",
                "localhost",
                "--port",
                "8880"
            ],
            "jinja": true,
            "justMyCode": true
        }
    ]
}

Then you can run and debug the application using the VS Code debugger.

Run the Broker

1. Run the taskiq worker

</code></pre>
<h2><a href="#user-content-development" aria-hidden="true" class="anchor" id="user-content-development"></a>Development</h2>
<h3><a href="#user-content-using-the-makefile" aria-hidden="true" class="anchor" id="user-content-using-the-makefile"></a>Using the Makefile</h3>
<p>The project includes a comprehensive Makefile for development tasks:</p>
<pre><code class="language-bash"># Show all available commands
make help

# Install package in development mode
make dev-install

# Run tests
make test

# Test CLI installation
make test-cli

# Format code
make format

# Run linting
make lint

# Run all checks (lint + test)
make check

# Clean build artifacts
make clean

# Build package
make build

# Publish to TestPyPI
make publish-test

# Publish to PyPI
make publish

# Complete release workflow
make release

Manual Development Setup

If you prefer manual setup:

1. Clone the repository:

   git clone https://github.com/Iamsdt/pyagenity-api.git
   cd pyagenity-api
   

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install in development mode:

   pip install -e .
   

4. Install development dependencies:

   pip install pytest pytest-cov ruff mypy pre-commit
   

5. Set up pre-commit hooks:

   pre-commit install
   

Testing

Run tests using pytest:

pytest src/tests/ -v --cov=pyagenity_api

Or use the Makefile:

make test

Publishing to PyPI

1. Test your package locally:

   make test-cli
   

2. Publish to TestPyPI first:

   make publish-test
   

3. If everything works, publish to PyPI:

   make publish
   

Resources

https://keda.sh/ Get all the fixers pytest --fixtures https://www.tutorialspoint.com/pytest/pytest_run_tests_in_parallel.html