opendataframework 0.0.4__tar.gz → 0.1.0__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 (106) hide show
  1. {opendataframework-0.0.4 → opendataframework-0.1.0}/LICENSE +1 -1
  2. opendataframework-0.1.0/PKG-INFO +358 -0
  3. opendataframework-0.1.0/README.md +341 -0
  4. opendataframework-0.1.0/pyproject.toml +65 -0
  5. opendataframework-0.1.0/src/opendataframework/__init__.py +74 -0
  6. opendataframework-0.1.0/src/opendataframework/component.py +131 -0
  7. opendataframework-0.1.0/src/opendataframework/config.py +156 -0
  8. opendataframework-0.1.0/src/opendataframework/context.py +885 -0
  9. opendataframework-0.1.0/src/opendataframework/entity.py +52 -0
  10. opendataframework-0.1.0/src/opendataframework/layer.py +130 -0
  11. opendataframework-0.1.0/src/opendataframework/logger.py +139 -0
  12. opendataframework-0.1.0/src/opendataframework/namespace.py +175 -0
  13. opendataframework-0.1.0/src/opendataframework/pipeline.py +88 -0
  14. opendataframework-0.1.0/src/opendataframework/project.py +163 -0
  15. opendataframework-0.1.0/src/opendataframework/repository.py +210 -0
  16. opendataframework-0.1.0/src/opendataframework/service.py +89 -0
  17. opendataframework-0.1.0/src/opendataframework/task.py +68 -0
  18. opendataframework-0.1.0/src/opendataframework/utils.py +26 -0
  19. opendataframework-0.1.0/src/opendataframework/view.py +189 -0
  20. opendataframework-0.0.4/PKG-INFO +0 -19
  21. opendataframework-0.0.4/README.md +0 -2
  22. opendataframework-0.0.4/pyproject.toml +0 -48
  23. opendataframework-0.0.4/setup.py +0 -73
  24. opendataframework-0.0.4/src/opendataframework/README.md +0 -43
  25. opendataframework-0.0.4/src/opendataframework/__init__.py +0 -3
  26. opendataframework-0.0.4/src/opendataframework/__main__.py +0 -2143
  27. opendataframework-0.0.4/src/opendataframework/analytics/setup.sh +0 -1
  28. opendataframework-0.0.4/src/opendataframework/analytics/superset/.env +0 -1
  29. opendataframework-0.0.4/src/opendataframework/analytics/superset/Dockerfile +0 -3
  30. opendataframework-0.0.4/src/opendataframework/analytics/superset/database/postgres/create.sh +0 -10
  31. opendataframework-0.0.4/src/opendataframework/analytics/superset/database/postgres/setup.sh +0 -25
  32. opendataframework-0.0.4/src/opendataframework/analytics/superset/docker-compose.yaml +0 -15
  33. opendataframework-0.0.4/src/opendataframework/analytics/superset/setup.sh +0 -16
  34. opendataframework-0.0.4/src/opendataframework/api/api-postgres/.env +0 -9
  35. opendataframework-0.0.4/src/opendataframework/api/api-postgres/Dockerfile +0 -16
  36. opendataframework-0.0.4/src/opendataframework/api/api-postgres/app/__init__.py +0 -11
  37. opendataframework-0.0.4/src/opendataframework/api/api-postgres/app/config.py +0 -17
  38. opendataframework-0.0.4/src/opendataframework/api/api-postgres/app/crud.py +0 -31
  39. opendataframework-0.0.4/src/opendataframework/api/api-postgres/app/database.py +0 -12
  40. opendataframework-0.0.4/src/opendataframework/api/api-postgres/app/dependencies.py +0 -11
  41. opendataframework-0.0.4/src/opendataframework/api/api-postgres/app/main.py +0 -46
  42. opendataframework-0.0.4/src/opendataframework/api/api-postgres/app/models.py +0 -32
  43. opendataframework-0.0.4/src/opendataframework/api/api-postgres/app/router.py +0 -76
  44. opendataframework-0.0.4/src/opendataframework/api/api-postgres/docker-compose.yaml +0 -16
  45. opendataframework-0.0.4/src/opendataframework/api/api-postgres/poetry.lock +0 -486
  46. opendataframework-0.0.4/src/opendataframework/api/api-postgres/pyproject.toml +0 -20
  47. opendataframework-0.0.4/src/opendataframework/api/inference/.env +0 -7
  48. opendataframework-0.0.4/src/opendataframework/api/inference/Dockerfile +0 -16
  49. opendataframework-0.0.4/src/opendataframework/api/inference/app/__init__.py +0 -11
  50. opendataframework-0.0.4/src/opendataframework/api/inference/app/config.py +0 -14
  51. opendataframework-0.0.4/src/opendataframework/api/inference/app/crud.py +0 -14
  52. opendataframework-0.0.4/src/opendataframework/api/inference/app/dependencies.py +0 -19
  53. opendataframework-0.0.4/src/opendataframework/api/inference/app/main.py +0 -39
  54. opendataframework-0.0.4/src/opendataframework/api/inference/app/models.py +0 -20
  55. opendataframework-0.0.4/src/opendataframework/api/inference/app/router.py +0 -18
  56. opendataframework-0.0.4/src/opendataframework/api/inference/docker-compose.yaml +0 -16
  57. opendataframework-0.0.4/src/opendataframework/api/inference/pyproject.toml +0 -20
  58. opendataframework-0.0.4/src/opendataframework/api/ingest.py +0 -179
  59. opendataframework-0.0.4/src/opendataframework/api/requirements.txt +0 -1
  60. opendataframework-0.0.4/src/opendataframework/api/setup.sh +0 -1
  61. opendataframework-0.0.4/src/opendataframework/devcontainers/R/.devcontainer/.Rprofile +0 -17
  62. opendataframework-0.0.4/src/opendataframework/devcontainers/R/.devcontainer/Dockerfile +0 -34
  63. opendataframework-0.0.4/src/opendataframework/devcontainers/R/.devcontainer/devcontainer.json +0 -43
  64. opendataframework-0.0.4/src/opendataframework/devcontainers/python/.devcontainer/Dockerfile +0 -3
  65. opendataframework-0.0.4/src/opendataframework/devcontainers/python/.devcontainer/devcontainer.json +0 -23
  66. opendataframework-0.0.4/src/opendataframework/docker-compose.yaml +0 -2
  67. opendataframework-0.0.4/src/opendataframework/docs/index.md +0 -1
  68. opendataframework-0.0.4/src/opendataframework/docs/mkdocs.yml +0 -56
  69. opendataframework-0.0.4/src/opendataframework/docs/requirements.txt +0 -1
  70. opendataframework-0.0.4/src/opendataframework/docs/stylesheets/extra.css +0 -8
  71. opendataframework-0.0.4/src/opendataframework/expectations.py +0 -76
  72. opendataframework-0.0.4/src/opendataframework/github/workflows/ci.yaml +0 -21
  73. opendataframework-0.0.4/src/opendataframework/hooks/.pre-commit-config.yaml +0 -29
  74. opendataframework-0.0.4/src/opendataframework/hooks/requirements.txt +0 -1
  75. opendataframework-0.0.4/src/opendataframework/layouts/research/.vscode/extensions.json +0 -8
  76. opendataframework-0.0.4/src/opendataframework/layouts/research/code/check/.gitkeep +0 -0
  77. opendataframework-0.0.4/src/opendataframework/layouts/research/code/learn/.gitkeep +0 -0
  78. opendataframework-0.0.4/src/opendataframework/layouts/research/code/share/.gitkeep +0 -0
  79. opendataframework-0.0.4/src/opendataframework/layouts/research/data/derived/.gitkeep +0 -0
  80. opendataframework-0.0.4/src/opendataframework/layouts/research/data/raw/.gitkeep +0 -0
  81. opendataframework-0.0.4/src/opendataframework/layouts/research/libraries/.gitkeep +0 -0
  82. opendataframework-0.0.4/src/opendataframework/layouts/research/logs/.gitkeep +0 -0
  83. opendataframework-0.0.4/src/opendataframework/layouts/research/models/.gitkeep +0 -0
  84. opendataframework-0.0.4/src/opendataframework/layouts/research/output/figures/.gitkeep +0 -0
  85. opendataframework-0.0.4/src/opendataframework/layouts/research/output/tables/.gitkeep +0 -0
  86. opendataframework-0.0.4/src/opendataframework/layouts/research/paper/.gitkeep +0 -0
  87. opendataframework-0.0.4/src/opendataframework/requirements.txt +0 -1
  88. opendataframework-0.0.4/src/opendataframework/setup.sh +0 -3
  89. opendataframework-0.0.4/src/opendataframework/storage/postgres/.env +0 -1
  90. opendataframework-0.0.4/src/opendataframework/storage/postgres/Dockerfile +0 -1
  91. opendataframework-0.0.4/src/opendataframework/storage/postgres/docker-compose.yaml +0 -16
  92. opendataframework-0.0.4/src/opendataframework/storage/postgres/setup.sh +0 -5
  93. opendataframework-0.0.4/src/opendataframework/storage/setup.sh +0 -1
  94. opendataframework-0.0.4/src/opendataframework/tests/__init__.py +0 -1
  95. opendataframework-0.0.4/src/opendataframework/tests/requirements.txt +0 -2
  96. opendataframework-0.0.4/src/opendataframework/tests/test_example.py +0 -6
  97. opendataframework-0.0.4/src/opendataframework/utility/nginx/Dockerfile +0 -5
  98. opendataframework-0.0.4/src/opendataframework/utility/nginx/docker-compose.yaml +0 -14
  99. opendataframework-0.0.4/src/opendataframework/utility/nginx/nginx.conf +0 -6
  100. opendataframework-0.0.4/src/opendataframework/utility/nginx/static/images/logo.svg +0 -7
  101. opendataframework-0.0.4/src/opendataframework/utility/nginx/static/index.html +0 -39
  102. opendataframework-0.0.4/src/opendataframework/utility/setup.sh +0 -1
  103. opendataframework-0.0.4/src/opendataframework/utility/texlive/Dockerfile +0 -3
  104. opendataframework-0.0.4/src/opendataframework/utility/texlive/docker-compose.yaml +0 -15
  105. opendataframework-0.0.4/src/opendataframework/utility/texlive/mnt/.gitkeep +0 -0
  106. /opendataframework-0.0.4/src/opendataframework/layouts/research/code/build/.gitkeep → /opendataframework-0.1.0/src/opendataframework/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2024 opendataframework
3
+ Copyright (c) 2026 opendataframework contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -0,0 +1,358 @@
1
+ Metadata-Version: 2.4
2
+ Name: opendataframework
3
+ Version: 0.1.0
4
+ Summary: Lightweight, config-driven dependency-injection framework for data applications.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Author: mykytapavlov
8
+ Author-email: mykytapavlov@users.noreply.github.com
9
+ Requires-Python: >=3.14
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.14
12
+ Project-URL: Documentation, https://opendataframework.github.io/opendataframework/
13
+ Project-URL: Homepage, https://opendataframework.github.io/opendataframework/
14
+ Project-URL: Repository, https://github.com/opendataframework/opendataframework
15
+ Description-Content-Type: text/markdown
16
+
17
+ # Open Data Framework
18
+
19
+ [![PyPI](https://img.shields.io/pypi/v/opendataframework)](https://pypi.org/project/opendataframework/)
20
+ [![Python](https://img.shields.io/badge/python-3.14%2B-blue)](https://www.python.org/downloads/)
21
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
22
+ [![Docs](https://img.shields.io/badge/docs-opendataframework.github.io-blue)](https://opendataframework.github.io/opendataframework/)
23
+
24
+ Lightweight dependency-injection framework for data applications.
25
+
26
+ This package provides structural abstractions —
27
+ `Entity`, `Repository`, `Component`, `Service`, `Task`, `Pipeline`,
28
+ `Layer`, `Namespace`, `Context`, `Project`, `Config`, `Logger`, `View`
29
+ — with zero third-party dependencies. No UI, no CLI, no MCP server.
30
+
31
+ > Need the CLI, UI, or MCP server? That's the
32
+ > [`odf`](https://opendataframework.github.io/odf/) package, which
33
+ > depends on this one.
34
+
35
+ Full documentation: **[opendataframework.github.io/opendataframework](https://opendataframework.github.io/opendataframework/)**
36
+
37
+ ---
38
+
39
+ # Why
40
+
41
+ Most data projects solve the same structural problems repeatedly: how to
42
+ wire dependencies, manage component lifecycles, and keep configuration
43
+ separate from code. This framework provides that plumbing as a small set
44
+ of reusable abstractions — `Entity`, `Repository`, `Component`, `Service`,
45
+ `Task`, `Pipeline` — so it doesn't need to be reinvented by hand in every
46
+ project.
47
+
48
+ > Want a ready-made project layout instead? Scaffolding an actual project
49
+ > from a template is the [`odf`](https://opendataframework.github.io/odf/)
50
+ > package's job — this is what that scaffold is built on.
51
+
52
+ ---
53
+
54
+ # Getting Started
55
+
56
+ Install:
57
+
58
+ ```bash
59
+ pip install opendataframework
60
+ ```
61
+
62
+ A minimal project needs three things: an entity and repository, a config
63
+ file, and a main file that starts the `Project`.
64
+
65
+ Application code (`app.py`):
66
+
67
+ ```python
68
+ import sqlite3
69
+ from dataclasses import dataclass
70
+
71
+ from opendataframework import Component, Config, Entity, Repository
72
+
73
+
74
+ @Entity
75
+ @dataclass
76
+ class User:
77
+ id: int
78
+ name: str
79
+
80
+
81
+ @Component
82
+ class SQLite:
83
+ def __init__(self, config: Config):
84
+ self.conn = sqlite3.connect(config.sqlite.path)
85
+ self.conn.execute(
86
+ "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"
87
+ )
88
+
89
+
90
+ @Repository(User)
91
+ class Users:
92
+ def __init__(self, sqlite: SQLite):
93
+ self.db = sqlite.conn
94
+
95
+ def all(self) -> list[User]:
96
+ rows = self.db.execute("SELECT id, name FROM users").fetchall()
97
+ return [User(id=row[0], name=row[1]) for row in rows]
98
+
99
+ def save(self, user: User) -> None:
100
+ self.db.execute("INSERT OR REPLACE INTO users VALUES (?, ?)", (user.id, user.name))
101
+ self.db.commit()
102
+ ```
103
+
104
+ Config file (`config.toml`):
105
+
106
+ ```toml
107
+ [sqlite]
108
+ path = "app.db"
109
+ ```
110
+
111
+ Main file (`main.py`):
112
+
113
+ ```python
114
+ from opendataframework import Project
115
+
116
+ from app import User, Users
117
+
118
+ project = Project.from_config("config.toml")
119
+ project.start()
120
+
121
+ users = project.context.get(Users)
122
+ users.save(User(id=1, name="Ada"))
123
+
124
+ print(users.all())
125
+ ```
126
+
127
+ `project.start()` blocks until every component has completed its
128
+ initialisation stage — there is no hidden latency on first access. Adding
129
+ a new component means declaring its dependencies in the constructor, not
130
+ writing wiring code — a config section is only needed if the component
131
+ reads from `Config` itself.
132
+
133
+ ---
134
+
135
+ # Core Concepts
136
+
137
+ ## Entity
138
+
139
+ A structured unit of data the system works with.
140
+
141
+ ```python
142
+ @Entity
143
+ @dataclass
144
+ class User:
145
+ id: int
146
+ name: str
147
+ ```
148
+
149
+ ## Repository
150
+
151
+ Manages Entities; abstracts persistence away from business logic.
152
+
153
+ ```python
154
+ @Repository(User)
155
+ class Users:
156
+ def get(self, user_id: int) -> User: ...
157
+ def save(self, user: User) -> None: ...
158
+ ```
159
+
160
+ ## View
161
+
162
+ An optional, single declaration a `Repository` attaches to itself: which
163
+ representation (table, map, image, video, ...) and field(s) best fit its
164
+ data. Metadata only — this package renders nothing itself. See
165
+ [View](https://opendataframework.github.io/opendataframework/view/).
166
+
167
+ ```python
168
+ @Repository(Store)
169
+ class Stores:
170
+ def all(self) -> list[Store]: ...
171
+
172
+ def data_view(self) -> LocationView:
173
+ return LocationView(fields=("lat", "lon"))
174
+ ```
175
+
176
+ ## Component
177
+
178
+ A `Context`-managed object with no required execution contract — wired in
179
+ and given its dependencies through the constructor.
180
+
181
+ ```python
182
+ @Component
183
+ class Classifier:
184
+ def fit(self, data): ...
185
+ def predict(self, data): ...
186
+ ```
187
+
188
+ ## Service
189
+
190
+ A long-running executable, wired through DI the same way as a `Component` but
191
+ with a mandatory `setup → run → stop` lifecycle — an API server, worker
192
+ process, or scheduler. `run()` blocks by nature; the framework backgrounds it
193
+ automatically.
194
+
195
+ ```python
196
+ @Service
197
+ class Postgres:
198
+ def setup(self): ...
199
+ def run(self): ...
200
+ def stop(self): ...
201
+ ```
202
+
203
+ ## Task
204
+
205
+ A finite executable, wired through DI the same way as a `Component` —
206
+ performs one bounded unit of work, once.
207
+
208
+ ```python
209
+ @Task
210
+ class MetricsFetcher:
211
+ def execute(self): ...
212
+ ```
213
+
214
+ ## Pipeline
215
+
216
+ Coordinates multiple `Task`s (and optionally other `Pipeline`s) into an
217
+ ordered workflow.
218
+
219
+ ```python
220
+ @Pipeline
221
+ class DailyAnalytics:
222
+ def execute(self): ...
223
+ ```
224
+
225
+ ## Layer
226
+
227
+ An organisational grouping — which subsystem a component belongs to
228
+ (`Api`, `Storage`, `Analytics`, `Messaging`, `Monitoring`, `Security`, or
229
+ custom). Independent of execution type.
230
+
231
+ ```python
232
+ @Storage
233
+ @Service
234
+ class Postgres: ...
235
+ ```
236
+
237
+ ## Namespace
238
+
239
+ The base class underlying every framework decorator — `Entity`,
240
+ `Component`, `Service`, `Task`, `Pipeline`, `Repository`, and `Layer` are
241
+ all `Namespace` subclasses, each with its own independent name → class
242
+ mapping. A framework extension point, not something end users subclass
243
+ directly. See
244
+ [Namespace](https://opendataframework.github.io/opendataframework/namespace/).
245
+
246
+ ## Config
247
+
248
+ Typed, dot-accessible view over a configuration dict — snake_case and
249
+ kebab-case are interchangeable, and nested sections chain naturally.
250
+ Resolved automatically into the container by `Project.from_config`.
251
+
252
+ ```python
253
+ @Storage
254
+ @Service
255
+ class Postgres:
256
+ def __init__(self, config: Config):
257
+ self.host = config.postgres.host
258
+ ```
259
+
260
+ ## Logger
261
+
262
+ Per-component logging handle, injectable via constructor DI like any
263
+ other dependency — writes land in that component's own log file with no
264
+ name argument needed.
265
+
266
+ ```python
267
+ @Task
268
+ class ExportUsers:
269
+ def __init__(self, users: Users, logger: Logger):
270
+ self.users = users
271
+ self.logger = logger
272
+
273
+ def execute(self) -> None:
274
+ self.logger.info("export starting")
275
+ ```
276
+
277
+ ## Context
278
+
279
+ Registers, resolves, and lifecycles every component in dependency order.
280
+ No circular dependencies — restructure with a shared third collaborator
281
+ instead.
282
+
283
+ ```python
284
+ component = project.context.get(UsersApi) # typed, by class
285
+ ```
286
+
287
+ ## Project
288
+
289
+ The composition root — owns `Context` and configuration, and is the
290
+ single entry point for starting and stopping the application.
291
+
292
+ ```python
293
+ project = Project.from_config("config.toml")
294
+ project.start()
295
+ ```
296
+
297
+ Multiple independent `Project` instances are supported in the same
298
+ process; there is no global mutable state.
299
+
300
+ ---
301
+
302
+ # Design Guidelines
303
+
304
+ * **Prefer composition** — decorators (`@Api @Service`), not inheritance
305
+ from framework base classes.
306
+ * **Keep responsibilities focused** — one primary reason to change per
307
+ class.
308
+ * **Avoid global mutable state** — framework state belongs to objects.
309
+ * **Avoid hidden magic** — dependencies must be visible in constructor
310
+ signatures.
311
+
312
+ ---
313
+
314
+ # Mental Model
315
+
316
+ ```text
317
+ Data is represented by Entities.
318
+ Repositories manage data.
319
+
320
+ Components provide capabilities.
321
+ Services run for extended periods.
322
+ Tasks execute bounded work.
323
+ Pipelines coordinate tasks (and other pipelines).
324
+
325
+ Layers organize components.
326
+ Context manages components and repositories.
327
+ Project owns everything.
328
+ ```
329
+
330
+ ---
331
+
332
+ # Examples
333
+
334
+ See [`examples/`](examples/README.md) — small, focused projects each
335
+ isolating one core abstraction.
336
+
337
+ > For the CLI, UI, MCP server, and chat surface
338
+ > built on top of this package, see `odf`.
339
+
340
+ ---
341
+
342
+ # Development
343
+
344
+ Requires Python >=3.14, managed with [Poetry](https://python-poetry.org/).
345
+
346
+ ```bash
347
+ poetry install # install dependencies, including dev
348
+ poetry run pytest # run the test suite
349
+ ```
350
+
351
+ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to propose changes.
352
+
353
+ ---
354
+
355
+ # License
356
+
357
+ [MIT](LICENSE)
358
+
@@ -0,0 +1,341 @@
1
+ # Open Data Framework
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/opendataframework)](https://pypi.org/project/opendataframework/)
4
+ [![Python](https://img.shields.io/badge/python-3.14%2B-blue)](https://www.python.org/downloads/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
6
+ [![Docs](https://img.shields.io/badge/docs-opendataframework.github.io-blue)](https://opendataframework.github.io/opendataframework/)
7
+
8
+ Lightweight dependency-injection framework for data applications.
9
+
10
+ This package provides structural abstractions —
11
+ `Entity`, `Repository`, `Component`, `Service`, `Task`, `Pipeline`,
12
+ `Layer`, `Namespace`, `Context`, `Project`, `Config`, `Logger`, `View`
13
+ — with zero third-party dependencies. No UI, no CLI, no MCP server.
14
+
15
+ > Need the CLI, UI, or MCP server? That's the
16
+ > [`odf`](https://opendataframework.github.io/odf/) package, which
17
+ > depends on this one.
18
+
19
+ Full documentation: **[opendataframework.github.io/opendataframework](https://opendataframework.github.io/opendataframework/)**
20
+
21
+ ---
22
+
23
+ # Why
24
+
25
+ Most data projects solve the same structural problems repeatedly: how to
26
+ wire dependencies, manage component lifecycles, and keep configuration
27
+ separate from code. This framework provides that plumbing as a small set
28
+ of reusable abstractions — `Entity`, `Repository`, `Component`, `Service`,
29
+ `Task`, `Pipeline` — so it doesn't need to be reinvented by hand in every
30
+ project.
31
+
32
+ > Want a ready-made project layout instead? Scaffolding an actual project
33
+ > from a template is the [`odf`](https://opendataframework.github.io/odf/)
34
+ > package's job — this is what that scaffold is built on.
35
+
36
+ ---
37
+
38
+ # Getting Started
39
+
40
+ Install:
41
+
42
+ ```bash
43
+ pip install opendataframework
44
+ ```
45
+
46
+ A minimal project needs three things: an entity and repository, a config
47
+ file, and a main file that starts the `Project`.
48
+
49
+ Application code (`app.py`):
50
+
51
+ ```python
52
+ import sqlite3
53
+ from dataclasses import dataclass
54
+
55
+ from opendataframework import Component, Config, Entity, Repository
56
+
57
+
58
+ @Entity
59
+ @dataclass
60
+ class User:
61
+ id: int
62
+ name: str
63
+
64
+
65
+ @Component
66
+ class SQLite:
67
+ def __init__(self, config: Config):
68
+ self.conn = sqlite3.connect(config.sqlite.path)
69
+ self.conn.execute(
70
+ "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"
71
+ )
72
+
73
+
74
+ @Repository(User)
75
+ class Users:
76
+ def __init__(self, sqlite: SQLite):
77
+ self.db = sqlite.conn
78
+
79
+ def all(self) -> list[User]:
80
+ rows = self.db.execute("SELECT id, name FROM users").fetchall()
81
+ return [User(id=row[0], name=row[1]) for row in rows]
82
+
83
+ def save(self, user: User) -> None:
84
+ self.db.execute("INSERT OR REPLACE INTO users VALUES (?, ?)", (user.id, user.name))
85
+ self.db.commit()
86
+ ```
87
+
88
+ Config file (`config.toml`):
89
+
90
+ ```toml
91
+ [sqlite]
92
+ path = "app.db"
93
+ ```
94
+
95
+ Main file (`main.py`):
96
+
97
+ ```python
98
+ from opendataframework import Project
99
+
100
+ from app import User, Users
101
+
102
+ project = Project.from_config("config.toml")
103
+ project.start()
104
+
105
+ users = project.context.get(Users)
106
+ users.save(User(id=1, name="Ada"))
107
+
108
+ print(users.all())
109
+ ```
110
+
111
+ `project.start()` blocks until every component has completed its
112
+ initialisation stage — there is no hidden latency on first access. Adding
113
+ a new component means declaring its dependencies in the constructor, not
114
+ writing wiring code — a config section is only needed if the component
115
+ reads from `Config` itself.
116
+
117
+ ---
118
+
119
+ # Core Concepts
120
+
121
+ ## Entity
122
+
123
+ A structured unit of data the system works with.
124
+
125
+ ```python
126
+ @Entity
127
+ @dataclass
128
+ class User:
129
+ id: int
130
+ name: str
131
+ ```
132
+
133
+ ## Repository
134
+
135
+ Manages Entities; abstracts persistence away from business logic.
136
+
137
+ ```python
138
+ @Repository(User)
139
+ class Users:
140
+ def get(self, user_id: int) -> User: ...
141
+ def save(self, user: User) -> None: ...
142
+ ```
143
+
144
+ ## View
145
+
146
+ An optional, single declaration a `Repository` attaches to itself: which
147
+ representation (table, map, image, video, ...) and field(s) best fit its
148
+ data. Metadata only — this package renders nothing itself. See
149
+ [View](https://opendataframework.github.io/opendataframework/view/).
150
+
151
+ ```python
152
+ @Repository(Store)
153
+ class Stores:
154
+ def all(self) -> list[Store]: ...
155
+
156
+ def data_view(self) -> LocationView:
157
+ return LocationView(fields=("lat", "lon"))
158
+ ```
159
+
160
+ ## Component
161
+
162
+ A `Context`-managed object with no required execution contract — wired in
163
+ and given its dependencies through the constructor.
164
+
165
+ ```python
166
+ @Component
167
+ class Classifier:
168
+ def fit(self, data): ...
169
+ def predict(self, data): ...
170
+ ```
171
+
172
+ ## Service
173
+
174
+ A long-running executable, wired through DI the same way as a `Component` but
175
+ with a mandatory `setup → run → stop` lifecycle — an API server, worker
176
+ process, or scheduler. `run()` blocks by nature; the framework backgrounds it
177
+ automatically.
178
+
179
+ ```python
180
+ @Service
181
+ class Postgres:
182
+ def setup(self): ...
183
+ def run(self): ...
184
+ def stop(self): ...
185
+ ```
186
+
187
+ ## Task
188
+
189
+ A finite executable, wired through DI the same way as a `Component` —
190
+ performs one bounded unit of work, once.
191
+
192
+ ```python
193
+ @Task
194
+ class MetricsFetcher:
195
+ def execute(self): ...
196
+ ```
197
+
198
+ ## Pipeline
199
+
200
+ Coordinates multiple `Task`s (and optionally other `Pipeline`s) into an
201
+ ordered workflow.
202
+
203
+ ```python
204
+ @Pipeline
205
+ class DailyAnalytics:
206
+ def execute(self): ...
207
+ ```
208
+
209
+ ## Layer
210
+
211
+ An organisational grouping — which subsystem a component belongs to
212
+ (`Api`, `Storage`, `Analytics`, `Messaging`, `Monitoring`, `Security`, or
213
+ custom). Independent of execution type.
214
+
215
+ ```python
216
+ @Storage
217
+ @Service
218
+ class Postgres: ...
219
+ ```
220
+
221
+ ## Namespace
222
+
223
+ The base class underlying every framework decorator — `Entity`,
224
+ `Component`, `Service`, `Task`, `Pipeline`, `Repository`, and `Layer` are
225
+ all `Namespace` subclasses, each with its own independent name → class
226
+ mapping. A framework extension point, not something end users subclass
227
+ directly. See
228
+ [Namespace](https://opendataframework.github.io/opendataframework/namespace/).
229
+
230
+ ## Config
231
+
232
+ Typed, dot-accessible view over a configuration dict — snake_case and
233
+ kebab-case are interchangeable, and nested sections chain naturally.
234
+ Resolved automatically into the container by `Project.from_config`.
235
+
236
+ ```python
237
+ @Storage
238
+ @Service
239
+ class Postgres:
240
+ def __init__(self, config: Config):
241
+ self.host = config.postgres.host
242
+ ```
243
+
244
+ ## Logger
245
+
246
+ Per-component logging handle, injectable via constructor DI like any
247
+ other dependency — writes land in that component's own log file with no
248
+ name argument needed.
249
+
250
+ ```python
251
+ @Task
252
+ class ExportUsers:
253
+ def __init__(self, users: Users, logger: Logger):
254
+ self.users = users
255
+ self.logger = logger
256
+
257
+ def execute(self) -> None:
258
+ self.logger.info("export starting")
259
+ ```
260
+
261
+ ## Context
262
+
263
+ Registers, resolves, and lifecycles every component in dependency order.
264
+ No circular dependencies — restructure with a shared third collaborator
265
+ instead.
266
+
267
+ ```python
268
+ component = project.context.get(UsersApi) # typed, by class
269
+ ```
270
+
271
+ ## Project
272
+
273
+ The composition root — owns `Context` and configuration, and is the
274
+ single entry point for starting and stopping the application.
275
+
276
+ ```python
277
+ project = Project.from_config("config.toml")
278
+ project.start()
279
+ ```
280
+
281
+ Multiple independent `Project` instances are supported in the same
282
+ process; there is no global mutable state.
283
+
284
+ ---
285
+
286
+ # Design Guidelines
287
+
288
+ * **Prefer composition** — decorators (`@Api @Service`), not inheritance
289
+ from framework base classes.
290
+ * **Keep responsibilities focused** — one primary reason to change per
291
+ class.
292
+ * **Avoid global mutable state** — framework state belongs to objects.
293
+ * **Avoid hidden magic** — dependencies must be visible in constructor
294
+ signatures.
295
+
296
+ ---
297
+
298
+ # Mental Model
299
+
300
+ ```text
301
+ Data is represented by Entities.
302
+ Repositories manage data.
303
+
304
+ Components provide capabilities.
305
+ Services run for extended periods.
306
+ Tasks execute bounded work.
307
+ Pipelines coordinate tasks (and other pipelines).
308
+
309
+ Layers organize components.
310
+ Context manages components and repositories.
311
+ Project owns everything.
312
+ ```
313
+
314
+ ---
315
+
316
+ # Examples
317
+
318
+ See [`examples/`](examples/README.md) — small, focused projects each
319
+ isolating one core abstraction.
320
+
321
+ > For the CLI, UI, MCP server, and chat surface
322
+ > built on top of this package, see `odf`.
323
+
324
+ ---
325
+
326
+ # Development
327
+
328
+ Requires Python >=3.14, managed with [Poetry](https://python-poetry.org/).
329
+
330
+ ```bash
331
+ poetry install # install dependencies, including dev
332
+ poetry run pytest # run the test suite
333
+ ```
334
+
335
+ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to propose changes.
336
+
337
+ ---
338
+
339
+ # License
340
+
341
+ [MIT](LICENSE)