flarchitect

https://lewis-morris.github.io/flarchitect/
Admin
flarchitect is a Flask extension that turns SQLAlchemy models into production-ready REST APIs with...
Tokens:4,549
Snippets:73
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and run quick start

Source: https://pypi.org/project/flarchitect

Commands to install the package and start the application.

```bash
pip install flarchitect
python app.py  # start your Flask app
# then visit http://localhost:5000/graphql
```

--------------------------------

### Install Flarchitect

Source: https://pypi.org/project/flarchitect

Commands to set up a virtual environment and install the package.

```bash
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
pip install flarchitect
python -c "import flarchitect; print(flarchitect.__version__)"
```

--------------------------------

### Run local test suite

Source: https://pypi.org/project/flarchitect

Install development dependencies and execute tests with required environment variables.

```bash
pip install -e .[dev]
export ACCESS_SECRET_KEY=access
export REFRESH_SECRET_KEY=refresh
pytest
```

--------------------------------

### Initialize Flarchitect API

Source: https://pypi.org/project/flarchitect

Basic setup for a Flask application using the Architect class.

```python
from flask import Flask
from flarchitect import Architect
from models import Author, BaseModel  # your SQLAlchemy models

app = Flask(__name__)
app.config["API_TITLE"] = "My API"
app.config["API_VERSION"] = "1.0"
app.config["API_BASE_MODEL"] = BaseModel
app.config["API_ALLOW_NESTED_WRITES"] = True

architect = Architect(app)

if __name__ == "__main__":
    app.run(debug=True)
```

--------------------------------

### Run tests with linting and coverage

Source: https://pypi.org/project/flarchitect

Install dependencies, fix linting issues, run tests, and generate coverage reports.

```bash
pip install -e .[dev]
ruff --fix .
export ACCESS_SECRET_KEY=access
export REFRESH_SECRET_KEY=refresh
pytest
```

```bash
bash scripts/coverage.sh
```

--------------------------------

### Example JSON Log Output

Source: https://pypi.org/project/flarchitect

Sample structure of a JSON log line emitted when API_JSON_LOGS is enabled.

```json
{
  "event": "log",
  "lvl": 1,
  "message": "Completed GET /api/items -> 200",
  "method": "GET",
  "path": "/api/items",
  "request_id": "e5f9c0c8f2ac4c58b6a1c5b6d8d3e9a1",
  "latency_ms": 12
}
```

--------------------------------

### Initialize Flarchitect with Flask

Source: https://pypi.org/project/flarchitect

Basic setup for integrating Flarchitect with a Flask application to enable automatic documentation and JSON specification endpoints.

```python
from flask import Flask
from flarchitect import Architect

app = Flask(__name__)
architect = Architect(app)  # Docs at /docs; JSON spec at /docs/apispec.json (canonical)
```

--------------------------------

### Request Serialization and Join Example

Source: https://pypi.org/project/flarchitect

Demonstrates how to override serialization types and specify join relationships in an API request.

```http
GET /api/invoices?dump=dynamic&join=invoice-lines,payments,customer
```

--------------------------------

### GET /api/{resource}

Source: https://pypi.org/project/flarchitect

Retrieves resources with optional control over serialization dump types and SQL join semantics.

```APIDOC
## GET /api/{resource}

### Description
Retrieves a collection of resources. Supports overriding serialization formats and configuring SQL join behavior via query parameters.

### Method
GET

### Endpoint
/api/{resource}

### Parameters
#### Query Parameters
- **dump** (string) - Optional - Controls serialization type: 'url' (default), 'json', 'dynamic', or 'hybrid'.
- **join** (string) - Optional - Comma-separated tokens for relationships to inline. Matches relationship keys or plural names.
- **join_type** (string) - Optional - Controls SQL join semantics: 'inner' (default), 'left', 'outer', or 'right'.

### Request Example
GET /api/invoices?dump=dynamic&join=invoice-lines,payments,customer
```

--------------------------------

### GET /docs/bundle

Source: https://pypi.org/project/flarchitect

Reports both generated and custom routes for mixed auto/manual deployments. It highlights path and method conflicts to assist teams in identifying overrides.

```APIDOC
## GET /docs/bundle

### Description
Reports both generated and custom routes, highlighting path/method conflicts so teams can spot overrides early.

### Method
GET

### Endpoint
/docs/bundle
```

--------------------------------

### Query items with filtering and pagination

Source: https://pypi.org/project/flarchitect

Example GraphQL query for retrieving items with name filtering and pagination arguments.

```graphql
query {
    all_items(name: "Foo", limit: 10, offset: 0) {
        id
        name
    }
}
```

--------------------------------

### GET /schema/discovery

Source: https://pypi.org/project/flarchitect

Retrieves available filterable fields, join tokens, and relationship paths for models at runtime. This endpoint helps frontend tooling and CLI clients understand the available operators, aggregation functions, and join paths.

```APIDOC
## GET /schema/discovery

### Description
Discover filterable fields, join tokens, and relationship paths at runtime. This endpoint returns the operators, aggregation functions, and join paths available for each model.

### Method
GET

### Endpoint
/schema/discovery
```

--------------------------------

### Enriched 403 Forbidden Error Response

Source: https://pypi.org/project/flarchitect

Example of the JSON response body returned when a request fails role-based access control checks.

```json
{
  "errors": {
    "error": "forbidden",
    "message": "Missing required role(s) for this action.",
    "required_roles": ["editor", "admin"],
    "any_of": false,
    "method": "POST",
    "path": "/api/widgets",
    "resource": "widgets",
    "user": {"id": 42, "username": "alice", "roles": ["member"]},
    "lookup": {"pk": 42, "lookups": {"username": "alice"}},
    "resolved_from": "POST",
    "reason": "missing_roles"
  }
}
```

--------------------------------

### Regenerate AI-ready documentation

Source: https://pypi.org/project/flarchitect

Update Markdown files and llms.txt from Sphinx sources.

```bash
python tools/convert_docs.py
```

--------------------------------

### Configure Basic Authentication

Source: https://pypi.org/project/flarchitect

Sets up basic authentication by defining the user model and credential verification method in the application configuration.

```python
app.config.update(
    API_AUTHENTICATE_METHOD=["basic"],
    API_USER_MODEL=User,
    API_USER_LOOKUP_FIELD="username",
    API_CREDENTIAL_CHECK_METHOD="check_password",
)
```

--------------------------------

### Configure Structured JSON Logging

Source: https://pypi.org/project/flarchitect

Enable production-ready JSON logging and adjust verbosity levels via application configuration.

```python
app.config.update(
    API_JSON_LOGS=True,       # emit JSON lines with context
    API_VERBOSITY_LEVEL=1,    # 0=quiet, higher=more verbose
    API_LOG_REQUESTS=True,    # default True; per-request completion log
)
```

--------------------------------

### Initialize GraphQL schema from models

Source: https://pypi.org/project/flarchitect

Generates a GraphQL schema from SQLAlchemy models and registers it with the architect instance.

```python
from flarchitect.graphql import create_schema_from_models

schema = create_schema_from_models([Item], db.session)
architect.init_graphql(schema=schema)
```

--------------------------------

### Test API Endpoint

Source: https://pypi.org/project/flarchitect

Use curl to verify the API is running.

```bash
curl http://localhost:5000/api/authors
```

--------------------------------

### Configure JWT Authentication

Source: https://pypi.org/project/flarchitect

Minimal configuration required to enable JWT authentication in the Flask app.

```python
app.config.update(
    API_AUTHENTICATE_METHOD=["jwt"],
    ACCESS_SECRET_KEY="access-secret",     # or set env var ACCESS_SECRET_KEY
    REFRESH_SECRET_KEY="refresh-secret",   # or set env var REFRESH_SECRET_KEY
    API_USER_MODEL=User,                    # your SQLAlchemy model
    API_USER_LOOKUP_FIELD="username",      # field used to find the user
    API_CREDENTIAL_CHECK_METHOD="check_password",  # method on User to verify password
)
```

--------------------------------

### Enable WebSocket broadcasts

Source: https://pypi.org/project/flarchitect

Configure the Flask application to support real-time WebSocket updates for CRUD operations.

```python
app.config.update(
    API_ENABLE_WEBSOCKETS=True,
    API_WEBSOCKET_PATH="/ws",  # optional
)
```

--------------------------------

### Configure API Key Authentication

Source: https://pypi.org/project/flarchitect

Provides two methods for API key authentication: using a custom lookup function or a hashed field on the user model.

```python
def lookup_user_by_token(token: str) -> User | None:
    return User.query.filter_by(api_key=token).first()

app.config.update(
    API_AUTHENTICATE_METHOD=["api_key"],
    API_KEY_AUTH_AND_RETURN_METHOD=staticmethod(lookup_user_by_token),
)
```

```python
app.config.update(
    API_AUTHENTICATE_METHOD=["api_key"],
    API_USER_MODEL=User,
    API_CREDENTIAL_HASH_FIELD="api_key_hash",
    API_CREDENTIAL_CHECK_METHOD="check_api_key",
)
```

--------------------------------

### Define Record-Level Access Policy

Source: https://pypi.org/project/flarchitect

Implements a policy class to enforce granular access control based on record ownership.

```python
class OwnerPolicy:
    def scope_query(self, query, *, user, model, **_):
        if user is None:
            return query.filter(False)
        return query.filter(model.owner_id == user.id)

    def can_read(self, obj, *, user, **_):
        return user is not None and getattr(obj, "owner_id", None) == user.id

    def can_create(self, data, *, user, **_):
        return user is not None and data.get("owner_id") == user.id

    def can_update(self, obj, data, *, user, **_):
        return user is not None and getattr(obj, "owner_id", None) == user.id

    def can_delete(self, obj, *, user, **_):
        return user is not None and getattr(obj, "owner_id", None) == user.id


app.config.update(
    API_AUTHENTICATE_METHOD=["custom"],
    API_CUSTOM_AUTH=my_custom_auth,
    API_ACCESS_POLICY=OwnerPolicy,
)
```

--------------------------------

### Define Route Authentication Requirements

Source: https://pypi.org/project/flarchitect

Configures which HTTP methods or route types require authentication using the API_AUTH_REQUIREMENTS dictionary.

```python
app.config.update(
    API_AUTHENTICATE_METHOD=["custom"],
    API_AUTH_REQUIREMENTS={
        "GET": False,  # list endpoints are public
        "GET_ONE": True,  # individual records still require auth
        "POST": True,
        "PATCH": True,
        "DELETE": True,
    },
)
```

--------------------------------

### Implement Role-Based Access Control

Source: https://pypi.org/project/flarchitect

Restricts route access using the require_roles decorator or a global configuration map for CRUD operations.

```python
from flarchitect.authentication import require_roles

@app.get("/admin")
@jwt_authentication
@require_roles("admin")
def admin_panel():
    ...
```

```python
app.config.update(
    API_AUTHENTICATE_METHOD=["jwt"],
    API_ROLE_MAP={
        "GET": ["viewer"],
        "POST": {"roles": ["editor", "admin"], "any_of": True},
        "DELETE": ["admin"],
    },
)
```

--------------------------------

### Perform record mutations

Source: https://pypi.org/project/flarchitect

GraphQL mutations for updating and deleting records.

```graphql
mutation {
    update_item(id: 1, name: "Bar") {
        id
        name
    }
}

mutation {
    delete_item(id: 1)
}
```

--------------------------------

### Map custom SQLAlchemy types

Source: https://pypi.org/project/flarchitect

Overrides default type mapping by providing a custom mapping dictionary to the schema generator.

```python
schema = create_schema_from_models(
    [Item], db.session, type_mapping={MyType: graphene.String}
)
```

--------------------------------

### Enable Request ID in JSON Response

Source: https://pypi.org/project/flarchitect

Include the correlation ID in the API response body by setting the configuration flag.

```python
app.config["API_DUMP_REQUEST_ID"] = True  # default False
```
Tokens:
Raw