Metadata-Version: 2.4
Name: GeneralManager
Version: 0.65.0
Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
Author-email: Tim Kleindick <tkleindick@yahoo.de>
License: MIT License
        
        Copyright (c) 2025 Tim Kleindick
        
        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/TimKleindick/general_manager
Project-URL: Documentation, https://timkleindick.github.io/general_manager/
Project-URL: Repository, https://github.com/TimKleindick/general_manager
Project-URL: Issues, https://github.com/TimKleindick/general_manager/issues
Project-URL: Changelog, https://github.com/TimKleindick/general_manager/releases
Keywords: django,orm,graphql,permissions,validation,caching,framework
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asgiref>=3.8.1
Requires-Dist: celery<6.0.0,>=5.3.6
Requires-Dist: channels>=4.1.0
Requires-Dist: Django>=5.2.15
Requires-Dist: django-simple-history>=3.8.0
Requires-Dist: exrex>=0.12.0
Requires-Dist: factory_boy>=3.3.3
Requires-Dist: Faker>=37.1.0
Requires-Dist: flexcache>=0.3
Requires-Dist: flexparser>=0.4
Requires-Dist: gitdb>=4.0.12
Requires-Dist: GitPython>=3.1.41
Requires-Dist: graphene>=3.4.3
Requires-Dist: graphene-django>=3.2.3
Requires-Dist: graphql-core>=3.2.6
Requires-Dist: graphql-relay>=3.2.0
Requires-Dist: numpy>=2.2.5
Requires-Dist: Pint>=0.24.4
Requires-Dist: platformdirs>=4.3.7
Requires-Dist: promise>=2.3
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: six>=1.17.0
Requires-Dist: smmap>=5.0.2
Requires-Dist: sqlparse>=0.5.4
Requires-Dist: text-unidecode>=1.3
Requires-Dist: typing_extensions>=4.13.2
Requires-Dist: tzdata>=2025.2
Provides-Extra: chat-ollama
Requires-Dist: ollama>=0.6.0; extra == "chat-ollama"
Provides-Extra: chat-openai
Requires-Dist: openai>=1.0.0; extra == "chat-openai"
Provides-Extra: chat-anthropic
Requires-Dist: anthropic>=0.34.0; extra == "chat-anthropic"
Provides-Extra: chat-google
Requires-Dist: google-genai>=1.0.0; extra == "chat-google"
Provides-Extra: file-upload-image
Requires-Dist: Pillow>=12.2.0; extra == "file-upload-image"
Provides-Extra: file-upload-s3
Requires-Dist: boto3>=1.42.0; extra == "file-upload-s3"
Requires-Dist: django-storages[s3]>=1.14; extra == "file-upload-s3"
Dynamic: license-file

# GeneralManager

[![PyPI](https://img.shields.io/pypi/v/GeneralManager.svg)](https://pypi.org/project/GeneralManager/)
[![Python](https://img.shields.io/pypi/pyversions/GeneralManager.svg)](https://pypi.org/project/GeneralManager/)
[![Build](https://github.com/TimKleindick/general_manager/actions/workflows/quality.yml/badge.svg?branch=main)](https://github.com/TimKleindick/general_manager/actions/workflows/quality.yml)
[![Coverage](https://img.shields.io/codecov/c/github/TimKleindick/general_manager)](https://app.codecov.io/gh/TimKleindick/general_manager)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/TimKleindick/general_manager/blob/main/LICENSE)

GeneralManager is a typed, declarative framework for building data-rich Django
applications. Define domain objects once, then use the same model through the
Django ORM, generated GraphQL, permission policies, validation, calculations,
search, and workflows.

GeneralManager is pre-1.0. The `main` branch and latest PyPI release can differ;
use the [release history](https://github.com/TimKleindick/general_manager/releases)
to distinguish published behavior from current development.

## What GeneralManager provides

### Domain models and interfaces

- Generate Django-backed models from typed manager definitions.
- Wrap [existing Django models](https://timkleindick.github.io/general_manager/concepts/interfaces/existing_model_interface/)
  or expose [calculated](https://timkleindick.github.io/general_manager/concepts/interfaces/computed_data_interfaces/),
  [request-backed](https://timkleindick.github.io/general_manager/concepts/interfaces/request_interface/),
  and remote data through the same manager API.

Start with the [architecture overview](https://timkleindick.github.io/general_manager/concepts/architecture/)
and [interface concepts](https://timkleindick.github.io/general_manager/concepts/interfaces/).

### APIs, permissions, and validation

- Generate [GraphQL](https://timkleindick.github.io/general_manager/concepts/graphql/)
  queries, mutations, subscriptions, filters, and pagination.
- Apply [manager-, operation-, object-, and field-level permission policies](https://timkleindick.github.io/general_manager/concepts/permission/).
- Keep business [validation](https://timkleindick.github.io/general_manager/concepts/rules_validation/)
  close to the domain with declarative rules.

### Data and operations

- Work with [unit- and currency-aware measurements](https://timkleindick.github.io/general_manager/concepts/measurement/)
  and [dataframe conversion helpers](https://timkleindick.github.io/general_manager/api/dataframes/).
- Coordinate derived values with [dependency-aware caching](https://timkleindick.github.io/general_manager/concepts/caching/),
  [search](https://timkleindick.github.io/general_manager/concepts/search/),
  [workflows](https://timkleindick.github.io/general_manager/concepts/workflow/),
  [audit logging](https://timkleindick.github.io/general_manager/concepts/observability/audit_logging/),
  and [metrics](https://timkleindick.github.io/general_manager/concepts/observability/graphql_metrics/).

### Development and optional integrations

- Seed realistic data with [generated factories and manager-landscape helpers](https://timkleindick.github.io/general_manager/concepts/factories/).
- Opt into [secure GraphQL file uploads](https://timkleindick.github.io/general_manager/concepts/graphql/file_uploads/)
  and [provider-based LLM chat](https://timkleindick.github.io/general_manager/concepts/chat_prompting/)
  when those subsystems fit the application.

## Compatibility

- Python 3.12 or newer
- Django 5.2.15 or newer
- CI exercises Python 3.12, 3.13, and 3.14 on SQLite

GeneralManager builds on Django's database layer, but this project only claims
backend support covered by its tests or maintained examples. SQLite,
PostgreSQL, and MariaDB are exercised by CI and are fully supported. Other
Django-supported backends may work, but are not currently claimed as supported
by GeneralManager.

## Five-minute setup

Start in an empty directory. On macOS or Linux:

```bash
mkdir general-manager-demo
cd general-manager-demo
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install GeneralManager
django-admin startproject gm_demo .
python manage.py startapp projects
```

Append the following to `gm_demo/settings.py`:

```python
INSTALLED_APPS += [
    "general_manager",
    "projects.apps.ProjectsConfig",
]

AUTOCREATE_GRAPHQL = True
GRAPHQL_URL = "graphql/"
ALLOWED_HOSTS = ["127.0.0.1", "localhost", "testserver"]
```

Create `projects/managers.py`:

```python
from typing import ClassVar

from django.db.models import CharField

from general_manager import GeneralManager
from general_manager.interface import DatabaseInterface
from general_manager.permission import AdditiveManagerPermission


class Project(GeneralManager):
    name: str

    class Interface(DatabaseInterface):
        name = CharField(max_length=100)

    class Permission(AdditiveManagerPermission):
        __read__: ClassVar[list[str]] = ["public"]
        __create__: ClassVar[list[str]] = ["isAuthenticated"]
        __update__: ClassVar[list[str]] = ["isAuthenticated"]
        __delete__: ClassVar[list[str]] = ["isAuthenticated"]
```

GeneralManager discovers `managers.py` modules in installed Django applications
during startup, so no manual import in `AppConfig.ready()` is needed. Create the
generated model's migration, initialize the database, and seed one demo record:

```bash
python manage.py makemigrations projects
python manage.py migrate
python manage.py shell -c 'from projects.managers import Project; Project.Factory.create(name="Apollo")'
python manage.py runserver
```

`Project.Factory.create(...)` is intended here for demo seeding. Application
writes should run through an authenticated permission context.

In another terminal, retrieve the record through generated GraphQL. This GET
request is copyable without a CSRF token:

```bash
curl --get 'http://127.0.0.1:8000/graphql/' \
  --data-urlencode 'query=query { projectList { items { name } } }'
```

Expected response:

```json
{"data":{"projectList":{"items":[{"name":"Apollo"}]}}}
```

You now have a typed manager, generated Django model, migration, persisted
record, permission policy, and generated GraphQL query. Continue with the
[annotated quickstart](https://timkleindick.github.io/general_manager/quickstart/)
for Windows activation, framework behavior, and troubleshooting.

## Documentation

- [Documentation home](https://timkleindick.github.io/general_manager/)
- [Quickstart](https://timkleindick.github.io/general_manager/quickstart/)
- [Installation and optional extras](https://timkleindick.github.io/general_manager/installation/)
- [Concept guides](https://timkleindick.github.io/general_manager/concepts/)
- [API reference](https://timkleindick.github.io/general_manager/api/core/)
- [Examples and recipes](https://timkleindick.github.io/general_manager/examples/)

## Project links

- [Releases](https://github.com/TimKleindick/general_manager/releases)
- [Issues](https://github.com/TimKleindick/general_manager/issues)
- [Contributing](https://github.com/TimKleindick/general_manager/blob/main/CONTRIBUTING.md)
- [MIT License](https://github.com/TimKleindick/general_manager/blob/main/LICENSE)
