Metadata-Version: 2.4
Name: tools2fast-fastapi
Version: 0.3.14
Summary: Shared tools, mixins, and base services for FastAPI applications - Solautyc Team internal use
Author-email: Angel Daniel Sanchez Castillo <angeldaniel.sanchezcastillo@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Angel Daniel Sanchez Castillo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/AngelDanielSanchezCastillo/tools2fast-fastapi
Project-URL: Documentation, https://github.com/AngelDanielSanchezCastillo/tools2fast-fastapi/tree/main/docs
Project-URL: Repository, https://github.com/AngelDanielSanchezCastillo/tools2fast-fastapi
Project-URL: Issues, https://github.com/AngelDanielSanchezCastillo/tools2fast-fastapi/issues
Keywords: fastapi,tools,mixins,services,sqlmodel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100.0
Requires-Dist: sqlmodel>=0.0.16
Dynamic: license-file

# Tools2Fast FastAPI

Shared tools, mixins, and base services for FastAPI applications. Designed for internal use by the Solautyc Team to standardize model definitions and common services across multiple packages.

> 📖 **Conventions reference**: this package follows the [2fast-handbook](https://github.com/AngelDanielSanchezCastillo/2fast-handbook) for ecosystem conventions (structure, versioning, README, commits, release).

## Installation

You can install this package from PyPI (if published) or use it locally within your workspace:

```bash
pip install tools2fast-fastapi
```

Locally with UV:
```bash
uv pip install -e path/to/tools2fast-fastapi
```

## Features

- **SQLModel Mixins**: Standardized `IdMixin`, `TimestampMixin`, and `AuditMixin`.
- **Base Models**: Core models setup to be inherited across all entity definitions.
- **Unified API envelope**: Success and error helpers via `APIResponse`.
- **Auth error helper**: `APIResponse.auth_error(...)` returns a ready-to-return
  `JSONResponse` with the project envelope and, for HTTP 401, the RFC 6750
  `WWW-Authenticate` header.
- **Shared Services**: Reusable services logic for basic CRUD and related queries (coming soon).

## Auth error contract

`APIResponse.auth_error` produces a stable contract for authentication and
authorization failures. The discriminator is `error.type` (never the message),
which lets clients react without string matching:

```python
from tools2fast_fastapi import APIResponse

return APIResponse.auth_error(
    error_code="TokenExpired",
    message="Token expirado",
    status_code=401,
    www_authenticate='Bearer error="expired_token"',
)
```

When the failure happens inside a **FastAPI dependency**, return a `Response`
is not enough (FastAPI injects it as the dependency value instead of
short-circuiting). Raise `AuthError` and register the handler once at startup:

```python
from fastapi import FastAPI
from tools2fast_fastapi import AuthError, install_auth_error_handler

app = FastAPI()
install_auth_error_handler(app)

async def get_current_user(...):
    raise AuthError(
        error_code="TokenExpired",
        message="Token expirado",
        www_authenticate='Bearer error="expired_token"',
    )
```

Both paths produce the same envelope and the same RFC 6750 header.

| Situation | Status | `error.type` | `WWW-Authenticate` |
|---|---|---|---|
| Missing token | 401 | `TokenMissing` | `Bearer` |
| Malformed / bad signature | 401 | `TokenInvalid` | `Bearer error="invalid_token"` |
| Expired token | 401 | `TokenExpired` | `Bearer error="expired_token"` |
| Email not verified | 403 | `EmailNotVerified` | — |
| Missing permission | 403 | `PermissionDenied` | — |
| Missing role | 403 | `RoleMissing` | — |
| Valid token, no tenant | 403 | `TenantRequired` | — |
| Inactive tenant | 403 | `TenantInactive` | — |

When `status_code` is `401` and `www_authenticate` is omitted, the header
defaults to `Bearer`. For any other status the header is omitted unless passed
explicitly.

## Documentation

See the `docs/` folder for more detailed instructions and usage guides:

- [Usage Guide](docs/guide.md)

## Examples

Check the `examples/` folder for sample implementation.

## License

This project is licensed under the MIT License.
