pyntral 1.0.0b1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. pyntral-1.0.0b1/.env.example +8 -0
  2. pyntral-1.0.0b1/CHANGELOG.md +26 -0
  3. pyntral-1.0.0b1/CONTRIBUTING.md +40 -0
  4. pyntral-1.0.0b1/LICENSE +17 -0
  5. pyntral-1.0.0b1/MANIFEST.in +12 -0
  6. pyntral-1.0.0b1/PKG-INFO +217 -0
  7. pyntral-1.0.0b1/README.md +178 -0
  8. pyntral-1.0.0b1/SECURITY.md +26 -0
  9. pyntral-1.0.0b1/admin/ArchiveNotice.tsx +9 -0
  10. pyntral-1.0.0b1/admin/AssetImage.tsx +17 -0
  11. pyntral-1.0.0b1/admin/CustomerProfile.tsx +31 -0
  12. pyntral-1.0.0b1/admin/Insights.tsx +54 -0
  13. pyntral-1.0.0b1/admin/OrderStatusBadge.tsx +15 -0
  14. pyntral-1.0.0b1/docs/README.md +35 -0
  15. pyntral-1.0.0b1/docs/api-reference.md +112 -0
  16. pyntral-1.0.0b1/docs/architecture.md +41 -0
  17. pyntral-1.0.0b1/docs/authentication.md +86 -0
  18. pyntral-1.0.0b1/docs/authorization.md +78 -0
  19. pyntral-1.0.0b1/docs/bridges.md +80 -0
  20. pyntral-1.0.0b1/docs/cli.md +85 -0
  21. pyntral-1.0.0b1/docs/deployment.md +53 -0
  22. pyntral-1.0.0b1/docs/events.md +97 -0
  23. pyntral-1.0.0b1/docs/extensions.md +89 -0
  24. pyntral-1.0.0b1/docs/filters.md +55 -0
  25. pyntral-1.0.0b1/docs/getting-started.md +85 -0
  26. pyntral-1.0.0b1/docs/logging.md +65 -0
  27. pyntral-1.0.0b1/docs/publishing.md +69 -0
  28. pyntral-1.0.0b1/docs/resources.md +119 -0
  29. pyntral-1.0.0b1/docs/troubleshooting.md +55 -0
  30. pyntral-1.0.0b1/docs/ui.md +91 -0
  31. pyntral-1.0.0b1/examples/__init__.py +0 -0
  32. pyntral-1.0.0b1/examples/basic/README.md +15 -0
  33. pyntral-1.0.0b1/examples/basic/__init__.py +1 -0
  34. pyntral-1.0.0b1/examples/basic/app.py +37 -0
  35. pyntral-1.0.0b1/examples/events/kafka_worker.py +28 -0
  36. pyntral-1.0.0b1/examples/events/rabbit_worker.py +29 -0
  37. pyntral-1.0.0b1/examples/shop/Dockerfile +30 -0
  38. pyntral-1.0.0b1/examples/shop/Dockerfile.dockerignore +22 -0
  39. pyntral-1.0.0b1/examples/shop/README.md +40 -0
  40. pyntral-1.0.0b1/examples/shop/__init__.py +0 -0
  41. pyntral-1.0.0b1/examples/shop/app.py +299 -0
  42. pyntral-1.0.0b1/examples/shop/compose.yaml +26 -0
  43. pyntral-1.0.0b1/pyntral.components.json +17 -0
  44. pyntral-1.0.0b1/pyproject.toml +60 -0
  45. pyntral-1.0.0b1/scripts/build_release.py +93 -0
  46. pyntral-1.0.0b1/scripts/smoke_installed.py +34 -0
  47. pyntral-1.0.0b1/setup.cfg +4 -0
  48. pyntral-1.0.0b1/src/pyntral/__init__.py +40 -0
  49. pyntral-1.0.0b1/src/pyntral/admin.py +828 -0
  50. pyntral-1.0.0b1/src/pyntral/auth.py +232 -0
  51. pyntral-1.0.0b1/src/pyntral/bridge.py +38 -0
  52. pyntral-1.0.0b1/src/pyntral/cli.py +478 -0
  53. pyntral-1.0.0b1/src/pyntral/events.py +244 -0
  54. pyntral-1.0.0b1/src/pyntral/filters.py +143 -0
  55. pyntral-1.0.0b1/src/pyntral/logging.py +260 -0
  56. pyntral-1.0.0b1/src/pyntral/orm.py +493 -0
  57. pyntral-1.0.0b1/src/pyntral/orm_types.py +37 -0
  58. pyntral-1.0.0b1/src/pyntral/resources.py +174 -0
  59. pyntral-1.0.0b1/src/pyntral/transports/__init__.py +4 -0
  60. pyntral-1.0.0b1/src/pyntral/transports/base.py +94 -0
  61. pyntral-1.0.0b1/src/pyntral/transports/kafka.py +115 -0
  62. pyntral-1.0.0b1/src/pyntral/transports/rabbitmq.py +105 -0
  63. pyntral-1.0.0b1/src/pyntral/typegen.py +185 -0
  64. pyntral-1.0.0b1/src/pyntral/ui/eslint.config.mjs +12 -0
  65. pyntral-1.0.0b1/src/pyntral/ui/index.html +8 -0
  66. pyntral-1.0.0b1/src/pyntral/ui/package.json +33 -0
  67. pyntral-1.0.0b1/src/pyntral/ui/public/favicon.svg +1 -0
  68. pyntral-1.0.0b1/src/pyntral/ui/scripts/lint-extensions.mjs +49 -0
  69. pyntral-1.0.0b1/src/pyntral/ui/src/App.tsx +607 -0
  70. pyntral-1.0.0b1/src/pyntral/ui/src/api.ts +46 -0
  71. pyntral-1.0.0b1/src/pyntral/ui/src/bridge.ts +10 -0
  72. pyntral-1.0.0b1/src/pyntral/ui/src/currentAdmin.tsx +13 -0
  73. pyntral-1.0.0b1/src/pyntral/ui/src/feedback.tsx +90 -0
  74. pyntral-1.0.0b1/src/pyntral/ui/src/filter-operator.tsx +98 -0
  75. pyntral-1.0.0b1/src/pyntral/ui/src/filter-state.ts +47 -0
  76. pyntral-1.0.0b1/src/pyntral/ui/src/filters.tsx +149 -0
  77. pyntral-1.0.0b1/src/pyntral/ui/src/main.tsx +10 -0
  78. pyntral-1.0.0b1/src/pyntral/ui/src/mutations.ts +75 -0
  79. pyntral-1.0.0b1/src/pyntral/ui/src/navigation.tsx +86 -0
  80. pyntral-1.0.0b1/src/pyntral/ui/src/popover.ts +74 -0
  81. pyntral-1.0.0b1/src/pyntral/ui/src/relation.tsx +31 -0
  82. pyntral-1.0.0b1/src/pyntral/ui/src/style.css +376 -0
  83. pyntral-1.0.0b1/src/pyntral/ui/src/theme.ts +22 -0
  84. pyntral-1.0.0b1/src/pyntral/ui/src/types.ts +123 -0
  85. pyntral-1.0.0b1/src/pyntral/ui/src/ui.tsx +325 -0
  86. pyntral-1.0.0b1/src/pyntral/ui/src/virtual.d.ts +11 -0
  87. pyntral-1.0.0b1/src/pyntral/ui/tests/filter-state.test.mjs +30 -0
  88. pyntral-1.0.0b1/src/pyntral/ui/tsconfig.json +74 -0
  89. pyntral-1.0.0b1/src/pyntral/ui/vite.config.ts +122 -0
  90. pyntral-1.0.0b1/src/pyntral/web_dist/assets/index-BmUJRJcd.css +1 -0
  91. pyntral-1.0.0b1/src/pyntral/web_dist/assets/index-D72npMvS.js +9 -0
  92. pyntral-1.0.0b1/src/pyntral/web_dist/favicon.svg +1 -0
  93. pyntral-1.0.0b1/src/pyntral/web_dist/index.html +10 -0
  94. pyntral-1.0.0b1/src/pyntral.egg-info/PKG-INFO +217 -0
  95. pyntral-1.0.0b1/src/pyntral.egg-info/SOURCES.txt +112 -0
  96. pyntral-1.0.0b1/src/pyntral.egg-info/dependency_links.txt +1 -0
  97. pyntral-1.0.0b1/src/pyntral.egg-info/entry_points.txt +2 -0
  98. pyntral-1.0.0b1/src/pyntral.egg-info/requires.txt +25 -0
  99. pyntral-1.0.0b1/src/pyntral.egg-info/top_level.txt +1 -0
  100. pyntral-1.0.0b1/tests/test_advanced_filters.py +205 -0
  101. pyntral-1.0.0b1/tests/test_api.py +242 -0
  102. pyntral-1.0.0b1/tests/test_bundled_spa.py +61 -0
  103. pyntral-1.0.0b1/tests/test_cli.py +180 -0
  104. pyntral-1.0.0b1/tests/test_contract.py +31 -0
  105. pyntral-1.0.0b1/tests/test_event_transports.py +315 -0
  106. pyntral-1.0.0b1/tests/test_events_core.py +243 -0
  107. pyntral-1.0.0b1/tests/test_features.py +178 -0
  108. pyntral-1.0.0b1/tests/test_logging.py +222 -0
  109. pyntral-1.0.0b1/tests/test_public_release.py +58 -0
  110. pyntral-1.0.0b1/tests/test_role_access.py +179 -0
  111. pyntral-1.0.0b1/tests/test_type_development.py +121 -0
  112. pyntral-1.0.0b1/tests/test_ui_contract.py +114 -0
  113. pyntral-1.0.0b1/tests/test_vite_extension_resolution.py +16 -0
  114. pyntral-1.0.0b1/tsconfig.json +3 -0
@@ -0,0 +1,8 @@
1
+ # Generate a hash: uv run pyntral hash-password
2
+ ADMIN_USERNAME=admin
3
+ ADMIN_PASSWORD_HASH=replace-with-scrypt-hash
4
+ # Generate: python -c 'import secrets; print(secrets.token_urlsafe(48))'
5
+ APP_SECRET_KEY=replace-with-48-random-chars
6
+ # LOCAL HTTP ONLY (set true in production HTTPS):
7
+ ADMIN_SECURE_COOKIE=false
8
+ DATABASE_URL=sqlite:///./shop.db
@@ -0,0 +1,26 @@
1
+ # Changelog
2
+
3
+ Pyntral releases follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) conventions and use [PEP 440](https://peps.python.org/pep-0440/) version numbers.
4
+
5
+ ## 1.0.0b1 — Initial public beta
6
+
7
+ ### Features
8
+
9
+ - FastAPI and SQLAlchemy 2.x resource registry with model-driven CRUD and relationships.
10
+ - React SPA with type-aware filters, relation selectors, forms, light/dark themes, toasts, dialogs, and customizable UI components.
11
+ - Local, model-based, and callback authentication with server-side resource, record, and field permissions.
12
+ - Pydantic bridges with generated TypeScript clients for custom React integrations.
13
+ - Structured logging with per-channel configuration and optional Loguru integration.
14
+ - Metadata-only events with an in-process bus and optional RabbitMQ and Kafka transports.
15
+ - Developer CLI with Vite integration, frontend caching, and a runnable sample application.
16
+ - English documentation, usage examples, contributor guidance, and a security policy.
17
+ - Watchable Pydantic bridge declarations, VS Code editor configuration, label-gated PR checks, and OIDC PyPI release workflow.
18
+
19
+ ### Known limitations
20
+
21
+ - Full browser E2E and live RabbitMQ/Kafka integration tests are not yet part of the verified release matrix.
22
+ - Transactional outbox, built-in broker dead-letter queue management, stable frontend lockfile, and published documentation hosting are future work.
23
+
24
+ See [release readiness](docs/deployment.md#release-readiness) for verification requirements.
25
+
26
+ - PyPI-first release pipeline embeds the generic SPA inside wheel/sdist; custom TSX builds remain optional for consuming applications.
@@ -0,0 +1,40 @@
1
+ # Contributing to Pyntral
2
+
3
+ Thanks for your interest in improving Pyntral. The project is in early beta and welcomes focused bug reports, tests, documentation improvements and reviewed pull requests.
4
+
5
+ ## Local setup
6
+
7
+ ```bash
8
+ uv sync --extra dev
9
+ uv run pytest -q
10
+ uv run pyntral doctor
11
+ uv run pyntral init-env
12
+ uv run pyntral dev examples.shop.app:app
13
+ ```
14
+
15
+ Node.js 22.12+ is required to build the React UI. The CLI stages files under `.pyntral/`; never commit this generated directory, `.env`, local databases, or credentials.
16
+
17
+ ## Code organization
18
+
19
+ - `src/pyntral/`: Python public API, session handling, ORM adapter, filtering, CLI, observability and event transports.
20
+ - `src/pyntral/ui/`: React/TypeScript SPA, shared controls and theme tokens.
21
+ - `admin/`: illustrative extension components.
22
+ - `examples/shop/`: working FastAPI + SQLite demonstration.
23
+ - `examples/events/`: broker worker patterns.
24
+ - `tests/`: Python integration tests and contracts.
25
+ - `docs/`: maintained documentation, API examples and deployment notes.
26
+
27
+ ## Change process
28
+
29
+ 1. Start from a branch and keep changes scoped to one feature or bug.
30
+ 2. Preserve backward compatibility within a published release series; document breaking changes explicitly.
31
+ 3. Add tests for API, authorization and event behavior changes. Never weaken CSRF/ACL tests to make a feature pass.
32
+ 4. Run `uv run pytest -q` and, when Node/npm are available, `uv run pyntral build --force`.
33
+ 5. Update the appropriate `docs/` page, README pointers and `CHANGELOG.md`.
34
+ 6. Use descriptive commits (for example `fix(ui): preserve select value when operator changes`).
35
+
36
+ Before publishing a release, generate and review `uv.lock`, review frontend lockfiles, test a built wheel (not only source imports), and validate the SPA in a real browser. The release manager should verify ownership/availability of package names and URLs.
37
+
38
+ ## Reporting bugs
39
+
40
+ Provide OS, Python/Node versions, version or commit, relevant redacted logs, a minimal reproduction, and expected/observed behavior. Remove secrets, session cookies, PII and database content. For security issues, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
@@ -0,0 +1,17 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 pyntral contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
@@ -0,0 +1,12 @@
1
+ include README.md LICENSE CHANGELOG.md CONTRIBUTING.md SECURITY.md
2
+ recursive-include docs *.md
3
+ recursive-include examples *.py *.md Dockerfile Dockerfile.dockerignore compose.yaml
4
+ recursive-include admin *.tsx
5
+ include pyntral.components.json
6
+ include .env.example
7
+ recursive-include src/pyntral/ui *
8
+ recursive-include src/pyntral/web_dist *
9
+ global-exclude __pycache__ *.py[cod] .DS_Store
10
+
11
+ recursive-include scripts *.py
12
+ include tsconfig.json
@@ -0,0 +1,217 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyntral
3
+ Version: 1.0.0b1
4
+ Summary: Extensible React admin console for FastAPI and SQLAlchemy
5
+ Author: pyntral contributors
6
+ License-Expression: MIT
7
+ Keywords: admin,fastapi,sqlalchemy,react,dashboard,crud
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Framework :: FastAPI
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
15
+ Requires-Python: >=3.11
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: fastapi<1,>=0.163
19
+ Requires-Dist: sqlalchemy<3,>=2.0.40
20
+ Requires-Dist: pydantic<3,>=2.12
21
+ Requires-Dist: uvicorn[standard]<1,>=0.40
22
+ Requires-Dist: itsdangerous<3,>=2.2
23
+ Provides-Extra: loguru
24
+ Requires-Dist: loguru<1,>=0.8; extra == "loguru"
25
+ Provides-Extra: rabbitmq
26
+ Requires-Dist: aio-pika==10.2.3; extra == "rabbitmq"
27
+ Provides-Extra: kafka
28
+ Requires-Dist: aiokafka==0.15.0; extra == "kafka"
29
+ Provides-Extra: all-events
30
+ Requires-Dist: aio-pika==10.2.3; extra == "all-events"
31
+ Requires-Dist: aiokafka==0.15.0; extra == "all-events"
32
+ Provides-Extra: dev
33
+ Requires-Dist: pytest<10,>=9; extra == "dev"
34
+ Requires-Dist: httpx<1,>=0.28; extra == "dev"
35
+ Requires-Dist: pytest-asyncio<2,>=1.2; extra == "dev"
36
+ Requires-Dist: aiosqlite<1,>=0.21; extra == "dev"
37
+ Requires-Dist: ruff<1,>=0.14; extra == "dev"
38
+ Dynamic: license-file
39
+
40
+ <div align="center">
41
+
42
+ # Pyntral
43
+
44
+ **A React-powered admin console for FastAPI and SQLAlchemy.**
45
+
46
+ Define your resources in Python. Get a searchable, customizable administration interface without writing CRUD screens.
47
+
48
+ **Python 3.11+** · **FastAPI** · **SQLAlchemy 2.x** · **React 19** · **TypeScript** · **MIT**
49
+
50
+ `1.0.0b1` · **Public beta** · [Get started](docs/getting-started.md) · [Documentation](docs/README.md) · [API reference](docs/api-reference.md)
51
+
52
+ </div>
53
+
54
+ ---
55
+
56
+ ## Why Pyntral?
57
+
58
+ Pyntral attaches a React single-page administration UI to an existing FastAPI application. SQLAlchemy mappings provide field types, relationships, and validation metadata; Python owns authentication, authorization, CRUD operations, and custom actions. React renders responsive forms, tables, filters, and extension components.
59
+
60
+ - **Model-driven CRUD** — register SQLAlchemy models, configure fields and relations, and manage records through one API.
61
+ - **Practical filtering** — type-aware operators, numeric/date ranges, enum include/exclude, and searchable foreign keys.
62
+ - **Built to extend** — nested navigation groups, custom pages, record actions, dialogs, field renderers, and a shared React component kit.
63
+ - **Authentication and access controls** — local credentials, SQLAlchemy-backed users, external identity callbacks, role thresholds, field visibility, and server-side authorization.
64
+ - **Typed Python ↔ React operations** — authenticated Pydantic bridges with generated TypeScript clients.
65
+ - **Event-oriented** — metadata-only events with in-process, optional RabbitMQ, or optional Kafka transports.
66
+ - **Developer-friendly** — `uv` workflows, Vite HMR, content-addressed frontend build caching in `.pyntral/`, and structured logging.
67
+
68
+ > **Release status:** Pyntral is an early beta. The Python API has automated tests; full browser and live-broker integration testing is still required before production adoption. See [limitations](docs/deployment.md#release-readiness).
69
+
70
+ ## Quick start
71
+
72
+ For a regular installation, only **Python 3.11+** is required. **Node.js 22.12+ and npm are needed only to compile custom React extensions** or develop Pyntral itself.
73
+
74
+ ```bash
75
+ # From this repository
76
+ uv sync --extra dev
77
+ uv run pyntral init-env
78
+ uv run pyntral dev examples.shop.app:app
79
+ ```
80
+
81
+ Open **http://127.0.0.1:5173/admin/** and sign in with the local account created by `init-env`. This demo seeds an example SQLite shop; it is not intended for real business data.
82
+
83
+ For live bridge types and VS Code autocomplete without rebuilding React:
84
+
85
+ ```bash
86
+ uv run pyntral types examples.shop.app:app --editor
87
+ uv run pyntral types examples.shop.app:app --watch
88
+ ```
89
+
90
+ For a production SPA build (ESLint checks on core and registered extensions, strict TypeScript and Vite):
91
+
92
+ ```bash
93
+ uv run pyntral build --force
94
+ # Bundle: .pyntral/dist/
95
+ ```
96
+
97
+ Install the **published Python package** in a FastAPI application:
98
+
99
+ ```bash
100
+ uv add pyntral
101
+ # Alternative:
102
+ pip install pyntral
103
+ ```
104
+
105
+ The default admin SPA is **already compiled into the Python wheel**. No npm install or `pyntral build` is necessary for normal SQLAlchemy resources, filters, auth or actions. See the [minimal Python-only example](examples/basic/README.md).
106
+
107
+ For applications with custom TSX fields, pages, dialogs or themes, use the *same Python dependency*, plus Node.js **at development/build time**:
108
+
109
+ ```bash
110
+ uv add pyntral
111
+ uv run pyntral types your_app.main:app --editor
112
+ uv run pyntral build --app your_app.main:app
113
+ ```
114
+
115
+ The resulting `.pyntral/dist/` overrides the packaged generic SPA for that application. See [custom extensions](docs/extensions.md) and [publishing](docs/publishing.md).
116
+
117
+ When working **inside this repository**, use `uv sync --extra rabbitmq` instead of adding Pyntral as its own dependency.
118
+
119
+ ## Define resources in Python
120
+
121
+ ```python
122
+ from fastapi import FastAPI
123
+ from sqlalchemy import create_engine
124
+ from sqlalchemy.orm import sessionmaker
125
+ from pyntral import Admin, LocalAuth, Resource, Field
126
+
127
+ from your_app.models import User, Order
128
+
129
+ engine = create_engine("sqlite:///./app.db")
130
+ SessionLocal = sessionmaker(engine, expire_on_commit=False)
131
+ app = FastAPI()
132
+
133
+ admin = Admin(
134
+ app,
135
+ session_factory=SessionLocal,
136
+ auth=LocalAuth.from_env(),
137
+ secret_key="replace-with-a-secret-at-least-32-characters-long",
138
+ secure_cookie=False, # LOCAL HTTP ONLY; use True behind HTTPS
139
+ title="My workspace",
140
+ )
141
+
142
+ admin.add_resource(Resource(
143
+ User,
144
+ visible_name=User.email,
145
+ search_fields=["email"],
146
+ fields={"password_hash": Field(visible=False)},
147
+ ))
148
+ admin.add_resource(Resource(Order))
149
+ ```
150
+
151
+ For deployable applications, supply secrets from environment variables and set `secure_cookie=True` under HTTPS. The complete runnable integration is in [`examples/shop/app.py`](examples/shop/app.py).
152
+
153
+ ## How it fits together
154
+
155
+ ```text
156
+ FastAPI app
157
+ └─ Pyntral Admin (/admin)
158
+ ├─ Auth, permissions, typed CRUD and relationship API
159
+ ├─ Resource / page / action / bridge registries
160
+ ├─ Optional metadata-only event transports
161
+ └─ React SPA
162
+ ├─ Type-aware tables, filters and forms
163
+ ├─ UI primitives and theme tokens
164
+ └─ Registered TSX extensions
165
+
166
+ PyPI wheel → bundled generic SPA → FastAPI
167
+ Custom TSX (optional): uv / npm → Vite → .pyntral/dist → FastAPI
168
+ ```
169
+
170
+ Your ORM definitions remain in Python. Resource metadata is delivered at runtime; adding another model does **not** require rebuilding React. Adding a new TypeScript extension does require the frontend compiler (handled by the CLI).
171
+
172
+ ## Documentation
173
+
174
+ | Start here | Customize | Operate |
175
+ | --- | --- | --- |
176
+ | [Installation & first app](docs/getting-started.md) | [Resources & relations](docs/resources.md) | [CLI & build cache](docs/cli.md) |
177
+ | [Architecture](docs/architecture.md) | [Filters](docs/filters.md) | [Logging](docs/logging.md) |
178
+ | [Python & HTTP API](docs/api-reference.md) | [React UI & theming](docs/ui.md) | [Events & brokers](docs/events.md) |
179
+ | [Authentication](docs/authentication.md) | [Custom components](docs/extensions.md) | [Deployment](docs/deployment.md) |
180
+ | [Authorization](docs/authorization.md) | [Typed bridges](docs/bridges.md) | [Troubleshooting](docs/troubleshooting.md) |
181
+
182
+ See the [complete documentation index](docs/README.md), [changelog](CHANGELOG.md), and [contribution guide](CONTRIBUTING.md).
183
+
184
+ ## Development
185
+
186
+ ```bash
187
+ uv sync --extra dev
188
+ uv run pytest -q
189
+ uv run pyntral doctor
190
+ uv run pyntral build
191
+ ```
192
+
193
+ The build command runs ESLint, TypeScript and Vite when developing custom frontend extensions. Release CI separately builds a generic SPA and bundles it in the PyPI wheel; consumers do not need Node.js for the standard admin. The tracked repository intentionally omits credentials, databases, generated assets, and `uv.lock` (to be generated and committed by the maintainer).
194
+
195
+ ## Security & support
196
+
197
+ Never expose the admin API without authentication and HTTPS. Resource authorization is enforced server-side; hiding navigation items is only a presentation choice. Event payloads contain identifiers and field metadata, **not field values**. Read [security guidance](SECURITY.md) before deploying; report vulnerabilities privately, not in public issues.
198
+
199
+ ## License
200
+
201
+ [MIT](LICENSE). Pyntral is an independent project; it is not affiliated with AdminJS.
202
+
203
+ ## Docker smoke test
204
+
205
+ Build and run the production shop example (no Vite dev server):
206
+
207
+ ```bash
208
+ docker compose -f examples/shop/compose.yaml build --progress=plain
209
+ docker compose -f examples/shop/compose.yaml up -d
210
+ ```
211
+
212
+ The image build runs ESLint, strict TypeScript checking, and Vite. See the
213
+ [shop Docker example](examples/shop/README.md) for setup and verification.
214
+
215
+ ## CI and publishing
216
+
217
+ CI for pull requests runs **only** when the `Run checks` label is added. Releases are published as **Python wheels and source distributions on PyPI** using GitHub OIDC Trusted Publishing. The compiled generic React SPA is packaged inside the Python distribution; no npm package is published. See [release setup](docs/publishing.md).
@@ -0,0 +1,178 @@
1
+ <div align="center">
2
+
3
+ # Pyntral
4
+
5
+ **A React-powered admin console for FastAPI and SQLAlchemy.**
6
+
7
+ Define your resources in Python. Get a searchable, customizable administration interface without writing CRUD screens.
8
+
9
+ **Python 3.11+** · **FastAPI** · **SQLAlchemy 2.x** · **React 19** · **TypeScript** · **MIT**
10
+
11
+ `1.0.0b1` · **Public beta** · [Get started](docs/getting-started.md) · [Documentation](docs/README.md) · [API reference](docs/api-reference.md)
12
+
13
+ </div>
14
+
15
+ ---
16
+
17
+ ## Why Pyntral?
18
+
19
+ Pyntral attaches a React single-page administration UI to an existing FastAPI application. SQLAlchemy mappings provide field types, relationships, and validation metadata; Python owns authentication, authorization, CRUD operations, and custom actions. React renders responsive forms, tables, filters, and extension components.
20
+
21
+ - **Model-driven CRUD** — register SQLAlchemy models, configure fields and relations, and manage records through one API.
22
+ - **Practical filtering** — type-aware operators, numeric/date ranges, enum include/exclude, and searchable foreign keys.
23
+ - **Built to extend** — nested navigation groups, custom pages, record actions, dialogs, field renderers, and a shared React component kit.
24
+ - **Authentication and access controls** — local credentials, SQLAlchemy-backed users, external identity callbacks, role thresholds, field visibility, and server-side authorization.
25
+ - **Typed Python ↔ React operations** — authenticated Pydantic bridges with generated TypeScript clients.
26
+ - **Event-oriented** — metadata-only events with in-process, optional RabbitMQ, or optional Kafka transports.
27
+ - **Developer-friendly** — `uv` workflows, Vite HMR, content-addressed frontend build caching in `.pyntral/`, and structured logging.
28
+
29
+ > **Release status:** Pyntral is an early beta. The Python API has automated tests; full browser and live-broker integration testing is still required before production adoption. See [limitations](docs/deployment.md#release-readiness).
30
+
31
+ ## Quick start
32
+
33
+ For a regular installation, only **Python 3.11+** is required. **Node.js 22.12+ and npm are needed only to compile custom React extensions** or develop Pyntral itself.
34
+
35
+ ```bash
36
+ # From this repository
37
+ uv sync --extra dev
38
+ uv run pyntral init-env
39
+ uv run pyntral dev examples.shop.app:app
40
+ ```
41
+
42
+ Open **http://127.0.0.1:5173/admin/** and sign in with the local account created by `init-env`. This demo seeds an example SQLite shop; it is not intended for real business data.
43
+
44
+ For live bridge types and VS Code autocomplete without rebuilding React:
45
+
46
+ ```bash
47
+ uv run pyntral types examples.shop.app:app --editor
48
+ uv run pyntral types examples.shop.app:app --watch
49
+ ```
50
+
51
+ For a production SPA build (ESLint checks on core and registered extensions, strict TypeScript and Vite):
52
+
53
+ ```bash
54
+ uv run pyntral build --force
55
+ # Bundle: .pyntral/dist/
56
+ ```
57
+
58
+ Install the **published Python package** in a FastAPI application:
59
+
60
+ ```bash
61
+ uv add pyntral
62
+ # Alternative:
63
+ pip install pyntral
64
+ ```
65
+
66
+ The default admin SPA is **already compiled into the Python wheel**. No npm install or `pyntral build` is necessary for normal SQLAlchemy resources, filters, auth or actions. See the [minimal Python-only example](examples/basic/README.md).
67
+
68
+ For applications with custom TSX fields, pages, dialogs or themes, use the *same Python dependency*, plus Node.js **at development/build time**:
69
+
70
+ ```bash
71
+ uv add pyntral
72
+ uv run pyntral types your_app.main:app --editor
73
+ uv run pyntral build --app your_app.main:app
74
+ ```
75
+
76
+ The resulting `.pyntral/dist/` overrides the packaged generic SPA for that application. See [custom extensions](docs/extensions.md) and [publishing](docs/publishing.md).
77
+
78
+ When working **inside this repository**, use `uv sync --extra rabbitmq` instead of adding Pyntral as its own dependency.
79
+
80
+ ## Define resources in Python
81
+
82
+ ```python
83
+ from fastapi import FastAPI
84
+ from sqlalchemy import create_engine
85
+ from sqlalchemy.orm import sessionmaker
86
+ from pyntral import Admin, LocalAuth, Resource, Field
87
+
88
+ from your_app.models import User, Order
89
+
90
+ engine = create_engine("sqlite:///./app.db")
91
+ SessionLocal = sessionmaker(engine, expire_on_commit=False)
92
+ app = FastAPI()
93
+
94
+ admin = Admin(
95
+ app,
96
+ session_factory=SessionLocal,
97
+ auth=LocalAuth.from_env(),
98
+ secret_key="replace-with-a-secret-at-least-32-characters-long",
99
+ secure_cookie=False, # LOCAL HTTP ONLY; use True behind HTTPS
100
+ title="My workspace",
101
+ )
102
+
103
+ admin.add_resource(Resource(
104
+ User,
105
+ visible_name=User.email,
106
+ search_fields=["email"],
107
+ fields={"password_hash": Field(visible=False)},
108
+ ))
109
+ admin.add_resource(Resource(Order))
110
+ ```
111
+
112
+ For deployable applications, supply secrets from environment variables and set `secure_cookie=True` under HTTPS. The complete runnable integration is in [`examples/shop/app.py`](examples/shop/app.py).
113
+
114
+ ## How it fits together
115
+
116
+ ```text
117
+ FastAPI app
118
+ └─ Pyntral Admin (/admin)
119
+ ├─ Auth, permissions, typed CRUD and relationship API
120
+ ├─ Resource / page / action / bridge registries
121
+ ├─ Optional metadata-only event transports
122
+ └─ React SPA
123
+ ├─ Type-aware tables, filters and forms
124
+ ├─ UI primitives and theme tokens
125
+ └─ Registered TSX extensions
126
+
127
+ PyPI wheel → bundled generic SPA → FastAPI
128
+ Custom TSX (optional): uv / npm → Vite → .pyntral/dist → FastAPI
129
+ ```
130
+
131
+ Your ORM definitions remain in Python. Resource metadata is delivered at runtime; adding another model does **not** require rebuilding React. Adding a new TypeScript extension does require the frontend compiler (handled by the CLI).
132
+
133
+ ## Documentation
134
+
135
+ | Start here | Customize | Operate |
136
+ | --- | --- | --- |
137
+ | [Installation & first app](docs/getting-started.md) | [Resources & relations](docs/resources.md) | [CLI & build cache](docs/cli.md) |
138
+ | [Architecture](docs/architecture.md) | [Filters](docs/filters.md) | [Logging](docs/logging.md) |
139
+ | [Python & HTTP API](docs/api-reference.md) | [React UI & theming](docs/ui.md) | [Events & brokers](docs/events.md) |
140
+ | [Authentication](docs/authentication.md) | [Custom components](docs/extensions.md) | [Deployment](docs/deployment.md) |
141
+ | [Authorization](docs/authorization.md) | [Typed bridges](docs/bridges.md) | [Troubleshooting](docs/troubleshooting.md) |
142
+
143
+ See the [complete documentation index](docs/README.md), [changelog](CHANGELOG.md), and [contribution guide](CONTRIBUTING.md).
144
+
145
+ ## Development
146
+
147
+ ```bash
148
+ uv sync --extra dev
149
+ uv run pytest -q
150
+ uv run pyntral doctor
151
+ uv run pyntral build
152
+ ```
153
+
154
+ The build command runs ESLint, TypeScript and Vite when developing custom frontend extensions. Release CI separately builds a generic SPA and bundles it in the PyPI wheel; consumers do not need Node.js for the standard admin. The tracked repository intentionally omits credentials, databases, generated assets, and `uv.lock` (to be generated and committed by the maintainer).
155
+
156
+ ## Security & support
157
+
158
+ Never expose the admin API without authentication and HTTPS. Resource authorization is enforced server-side; hiding navigation items is only a presentation choice. Event payloads contain identifiers and field metadata, **not field values**. Read [security guidance](SECURITY.md) before deploying; report vulnerabilities privately, not in public issues.
159
+
160
+ ## License
161
+
162
+ [MIT](LICENSE). Pyntral is an independent project; it is not affiliated with AdminJS.
163
+
164
+ ## Docker smoke test
165
+
166
+ Build and run the production shop example (no Vite dev server):
167
+
168
+ ```bash
169
+ docker compose -f examples/shop/compose.yaml build --progress=plain
170
+ docker compose -f examples/shop/compose.yaml up -d
171
+ ```
172
+
173
+ The image build runs ESLint, strict TypeScript checking, and Vite. See the
174
+ [shop Docker example](examples/shop/README.md) for setup and verification.
175
+
176
+ ## CI and publishing
177
+
178
+ CI for pull requests runs **only** when the `Run checks` label is added. Releases are published as **Python wheels and source distributions on PyPI** using GitHub OIDC Trusted Publishing. The compiled generic React SPA is packaged inside the Python distribution; no npm package is published. See [release setup](docs/publishing.md).
@@ -0,0 +1,26 @@
1
+ # Security policy
2
+
3
+ Pyntral is a **public beta**, not a certified security product. Do not expose it to the public Internet without a reviewed authentication, authorization, HTTPS and deployment configuration.
4
+
5
+ ## Reporting vulnerabilities
6
+
7
+ If a private maintainer contact is available on the eventual repository, use that confidential channel. Until a private reporting address is published, **do not post exploit details or credentials in a public issue**; contact the maintainer privately through an existing trusted channel. This repository does not yet claim a dedicated security response SLA.
8
+
9
+ ## Deployment expectations
10
+
11
+ - Require HTTPS and `secure_cookie=True` outside localhost.
12
+ - Use a strong, stable secret key stored outside the source tree and rotate it as part of an incident response plan.
13
+ - Configure real user authentication and server-side resource/row/field permissions.
14
+ - Do not return passwords, secrets or sensitive media URLs through resource fields, bridges, custom callbacks or logs.
15
+ - Use CSRF-aware API clients for mutations; restrict CORS and embedding appropriately at the proxy/host layer.
16
+ - Rate-limit login endpoints via host infrastructure if exposed to untrusted networks.
17
+ - Restrict RabbitMQ/Kafka credentials and topics/queues to trusted services. Broker payloads contain IDs and metadata but no application-level ACL filtering.
18
+ - Run dependency scanning and a security review before a stable production release.
19
+
20
+ ## Supported versions
21
+
22
+ | Version | Security support |
23
+ | --- | --- |
24
+ | `1.0.0b1` | Best-effort beta maintenance; no guaranteed SLA |
25
+
26
+ See [authentication](docs/authentication.md), [authorization](docs/authorization.md) and [deployment](docs/deployment.md).
@@ -0,0 +1,9 @@
1
+ import type { ActionDialogProps } from "@pyntral/types";
2
+
3
+ /** Pluggable body for a contextual record action confirmation dialog. */
4
+ export default function ArchiveNotice({ record }: ActionDialogProps) {
5
+ return <div style={{ marginTop: 16, fontSize: 13, lineHeight: 1.6 }}>
6
+ <p>Archive <strong>{String(record.name ?? "this customer")}</strong>?</p>
7
+ <p style={{ color: "var(--ra-muted)" }}>The record will remain in the database, but its active flag will be disabled.</p>
8
+ </div>;
9
+ }
@@ -0,0 +1,17 @@
1
+ import { useQuery } from "@tanstack/react-query";
2
+ import { resolveAsset } from "@pyntral/generated";
3
+ import type { CustomFieldProps } from "@pyntral/types";
4
+
5
+ /** Demonstrates Entity.Agent.cover_id -> Entity.FileAsset -> Python bridge -> image URL. */
6
+ export default function AssetImage({ record }: CustomFieldProps) {
7
+ const id = record.cover_id;
8
+ const asset = useQuery({
9
+ queryKey: ["asset-url", id], enabled: id !== null && id !== undefined,
10
+ queryFn: () => resolveAsset({ asset_id: Number(id) }),
11
+ });
12
+ if (id == null) return <span className="muted">No asset</span>;
13
+ if (asset.isPending) return <span className="muted">Loading…</span>;
14
+ if (!asset.data || asset.error) return <span className="muted">Not available</span>;
15
+ return <img src={asset.data.url} alt={asset.data.filename} width={34} height={34}
16
+ style={{ borderRadius: 8, objectFit: "cover", verticalAlign: "middle" }} />;
17
+ }
@@ -0,0 +1,31 @@
1
+ import { useState } from "react";
2
+ import { useAdminFeedback } from "@pyntral/feedback";
3
+ import type { CustomActionProps } from "@pyntral/types";
4
+
5
+ /** A full custom record action page, with the current entity and submit callback. */
6
+ export default function CustomerProfile({ record, resource, invoke, navigate }: CustomActionProps) {
7
+ const feedback = useAdminFeedback();
8
+ const [response, setResponse] = useState<unknown>(null);
9
+ const [error, setError] = useState("");
10
+ return <div className="surface" style={{ padding: 22, maxWidth: 560 }}>
11
+ <h2>{String(record.name ?? "Customer")}</h2>
12
+ <p>Email: {String(record.email ?? "—")}</p>
13
+ <p>This page is a React action extension. Its props contain the current record.</p>
14
+ <button className="btn primary" onClick={async () => {
15
+ const accepted = await feedback.confirm({ title: "Load customer profile?",
16
+ message: `Fetch details for ${String(record.name ?? "this customer")}?`,
17
+ confirmLabel: "Fetch profile" });
18
+ if (!accepted) return;
19
+ try { setResponse(await invoke({})); setError(""); }
20
+ catch (reason) {
21
+ const message = reason instanceof Error ? reason.message : "Action failed";
22
+ setError(message);
23
+ feedback.toast(message, { kind: "error" });
24
+ }
25
+ }}>Call Python handler</button>
26
+ {error && <p role="alert">{error}</p>}
27
+ {response != null && <pre>{JSON.stringify(response, null, 2)}</pre>}
28
+ <button className="btn subtle" style={{ marginLeft: 8 }}
29
+ onClick={() => navigate(`resources/${resource.id}`)}>Back to customers</button>
30
+ </div>;
31
+ }
@@ -0,0 +1,54 @@
1
+ import { useState } from "react";
2
+ import { ArrowRight, Bell, Image as ImageIcon } from "lucide-react";
3
+ import type { CustomPageProps } from "@pyntral/types";
4
+ import { useAdminFeedback } from "@pyntral/feedback";
5
+ import { AsyncSelect, Badge, Button, Card, DatePicker, Dialog, SearchInput, Select, TextInput,
6
+ type SelectOption } from "@pyntral/ui";
7
+ import { api } from "@pyntral/api";
8
+
9
+ /** Demonstrates that extensions use the same UI primitives/theme/feedback as the core. */
10
+ export default function Insights({ schema, navigate }: CustomPageProps) {
11
+ const feedback = useAdminFeedback();
12
+ const [text, setText] = useState("");
13
+ const [search, setSearch] = useState("");
14
+ const [date, setDate] = useState<string | null>(null);
15
+ const [roles, setRoles] = useState<(string | number)[]>(["reviewer", "author"]);
16
+ const [agentId, setAgentId] = useState<string | number | null>(null);
17
+ const [dialog, setDialog] = useState(false);
18
+ const loadAgents = async (q: string): Promise<SelectOption[]> =>
19
+ (await api<{ items: SelectOption[] }>(`/api/resources/agents/options?q=${encodeURIComponent(q)}`)).items;
20
+
21
+ return <section>
22
+ <h1>Component playground</h1>
23
+ <p style={{ color: "var(--ra-muted)", fontSize: 12 }}>A custom page using the public @pyntral/ui and @pyntral/feedback API.</p>
24
+ <div className="resource-grid" style={{ marginBottom: 20 }}>
25
+ <Card title="Reusable controls" description="Light/dark tokens inherited automatically">
26
+ <div style={{ display: "grid", gap: 12 }}>
27
+ <TextInput value={text} onChange={(e) => setText(e.target.value)} placeholder="Regular input" aria-label="Demo input"/>
28
+ <SearchInput value={search} onChange={setSearch} showSubmit submitPosition="outside" onSearch={() => feedback.toast(`Search: ${search}`)}/>
29
+ <Select<string | number> multiple value={roles} onChange={(value) => setRoles(Array.isArray(value) ? value : [])}
30
+ maxItems={2} options={["reviewer", "author", "admin", "reader", "moderator", "support"].map((role) => ({ label: role, value: role }))}/>
31
+ <AsyncSelect value={agentId} onChange={(value) => setAgentId(Array.isArray(value) ? value[0] ?? null : value)}
32
+ loadOptions={loadAgents} placeholder="Find agent (remote search)…"/>
33
+ <DatePicker value={date} onChange={setDate}/>
34
+ <div style={{ display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
35
+ <Badge tone="success">Active</Badge><Badge tone="primary">Preview</Badge><Badge>Draft</Badge>
36
+ </div>
37
+ <Button variant="primary" startIcon={<Bell size={16}/>} onClick={() => feedback.toast("All controls use the same feedback service", { kind: "success" })}>Show toast</Button>
38
+ <Button variant="secondary" onClick={() => setDialog(true)} startIcon={<ImageIcon size={16}/>}>Open dialog</Button>
39
+ </div>
40
+ </Card>
41
+ <Card title="Registered resources" description={`${schema.resources.length} resources available`}>
42
+ <div style={{ display: "grid", gap: 6 }}>
43
+ {schema.resources.map((resource) => <Button key={resource.id} variant="ghost"
44
+ endIcon={<ArrowRight size={15}/>} onClick={() => navigate(`resources/${resource.id}`)}>
45
+ {resource.label}
46
+ </Button>)}
47
+ </div>
48
+ </Card>
49
+ </div>
50
+ <Dialog open={dialog} onClose={() => setDialog(false)} title="Custom dialog" footer={<Button variant="primary" onClick={() => setDialog(false)}>Close</Button>}>
51
+ <p style={{ color: "var(--ra-text-secondary)" }}>Dialogs can contain any React component, including forms and bridge-backed widgets.</p>
52
+ </Dialog>
53
+ </section>;
54
+ }