docs: collect refreshed mongo-ops wiki site (API-correct overhaul, v0.1.5)
This commit is contained in:
@@ -530,7 +530,7 @@
|
||||
|
||||
|
||||
<span class="md-ellipsis">
|
||||
02 components
|
||||
Core Components
|
||||
|
||||
</span>
|
||||
|
||||
@@ -1028,26 +1028,33 @@
|
||||
|
||||
|
||||
<h1 id="mongo-ops-async-mongodb-operations-layer-for-fastapi">🧩 mongo-ops — Async MongoDB Operations Layer for FastAPI</h1>
|
||||
<p><code>mongo-ops</code> is a modular, high-performance MongoDB operations library designed for FastAPI microservices.
|
||||
It standardizes repository patterns, async CRUD operations, and model management — with extensible components for both Beanie and Motor.</p>
|
||||
<p><code>mongo-ops</code> is a modular, high-performance MongoDB operations library for FastAPI microservices. It standardizes connection lifecycle, Pydantic v2 document models, and repository-style async CRUD — with added layers for caching, reference population, and multi-document transactions. It is built on top of Motor.</p>
|
||||
<blockquote>
|
||||
<p><strong>Doc model:</strong> this wiki is written for humans — how‑to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine‑readable bundle under <code>docs/mcp/</code>.</p>
|
||||
</blockquote>
|
||||
<hr />
|
||||
<h2 id="key-features">🚀 Key Features</h2>
|
||||
<ul>
|
||||
<li>🧱 Unified repository pattern for MongoDB collections</li>
|
||||
<li>🧱 Unified repository pattern — <code>BaseRepository</code> with generic CRUD</li>
|
||||
<li>⚡ Fully asynchronous (Motor-based)</li>
|
||||
<li>🧬 Pydantic v2 data model integration</li>
|
||||
<li>🧰 Built-in CRUD and aggregation utilities</li>
|
||||
<li>🔒 Transaction and session helpers</li>
|
||||
<li>🧩 Optional Beanie ORM integration</li>
|
||||
<li>🧪 Pytest-friendly architecture</li>
|
||||
<li>🧬 Pydantic v2 data models with auto‑timestamps (<code>BaseDocument</code>)</li>
|
||||
<li>🔒 Model registry for multi-collection startup (<code>ModelRegistry</code>)</li>
|
||||
<li>🗄️ ID-based caching — in-memory or Redis (<code>cache/</code>)</li>
|
||||
<li>🔗 Reference population with cycle detection (<code>populate/</code>)</li>
|
||||
<li>🔁 Transaction and session helpers (<code>transactions/</code>)</li>
|
||||
<li>🧪 Mock-friendly architecture — the whole repo test suite runs without MongoDB</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="installation">📦 Installation</h2>
|
||||
<p>From your internal PyPI:</p>
|
||||
<div class="language-bash highlight"><span class="filename">Bash</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>pip<span class="w"> </span>install<span class="w"> </span>--extra-index-url<span class="w"> </span>https://<span class="nv">$PYPI_USERNAME</span>:<span class="nv">$PYPI_PASSWORD</span>@pip.aetoskia.com/simple<span class="w"> </span>mongo-ops
|
||||
</code></pre></div>
|
||||
<p>With the extra batteries your workload needs:</p>
|
||||
<div class="language-bash highlight"><span class="filename">Bash</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>pip<span class="w"> </span>install<span class="w"> </span>--extra-index-url<span class="w"> </span>https://<span class="nv">$PYPI_USERNAME</span>:<span class="nv">$PYPI_PASSWORD</span>@pip.aetoskia.com/simple<span class="w"> </span><span class="s2">"mongo-ops[redis]"</span><span class="w"> </span><span class="c1"># Redis cache backend</span>
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>pip<span class="w"> </span>install<span class="w"> </span>--extra-index-url<span class="w"> </span>https://<span class="nv">$PYPI_USERNAME</span>:<span class="nv">$PYPI_PASSWORD</span>@pip.aetoskia.com/simple<span class="w"> </span><span class="s2">"mongo-ops[all]"</span><span class="w"> </span><span class="c1"># dev, redis, beanie, fastapi</span>
|
||||
</code></pre></div>
|
||||
<p>From local source:</p>
|
||||
<div class="language-bash highlight"><span class="filename">Bash</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.
|
||||
<div class="language-bash highlight"><span class="filename">Bash</span><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.
|
||||
</code></pre></div>
|
||||
<hr />
|
||||
<h2 id="documentation-structure">📁 Documentation Structure</h2>
|
||||
@@ -1061,31 +1068,87 @@ It standardizes repository patterns, async CRUD operations, and model management
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><a href="01_overview/">Overview</a></td>
|
||||
<td>Core concept and architecture overview</td>
|
||||
<td>Architecture, lifecycle, and repository decision table</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="02_components/">Core Components</a></td>
|
||||
<td><code>BaseDocument</code>, <code>MongoConnectionManager</code>, <code>BaseRepository</code></td>
|
||||
<td>Validated reference for the public API surface</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="03_use_cases/01_basic_crud/">Use Cases</a></td>
|
||||
<td>CRUD, transactions, pagination, and more</td>
|
||||
<td><strong>Use cases</strong></td>
|
||||
<td>Step-by-step recipes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/01_basic_crud/">01 – Basic CRUD API</a></td>
|
||||
<td>FastAPI user management app</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/02_custom_repo/">02 – Custom repository</a></td>
|
||||
<td>Product catalog with business logic</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/03_transactions/">03 – Transactions</a></td>
|
||||
<td>Atomic order + inventory updates</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/04_pagination/">04 – Pagination</a></td>
|
||||
<td>Filtering, sorting, page metadata</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/05_soft_deletes/">05 – Soft deletes</a></td>
|
||||
<td>Recoverable delete pattern</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/06_multi_model/">06 – Multi-model</a></td>
|
||||
<td>One service, many collections</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/07_caching/">07 – Caching</a></td>
|
||||
<td>In-memory / Redis read cache</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/08_population/">08 – Population</a></td>
|
||||
<td>Resolve references on read</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/09_advanced_population/">09 – Advanced population</a></td>
|
||||
<td>Nested + circular references</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/10_cache_and_population/">10 – Cache + population</a></td>
|
||||
<td>Reading through cache, populating on hit</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/11_cache_lifecycle/">11 – Cache lifecycle</a></td>
|
||||
<td>Startup/shutdown hygiene</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/12_transaction_helper/">12 – Transaction helper</a></td>
|
||||
<td><code>execute_transaction</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/13_index_creation/">13 – Indexes</a></td>
|
||||
<td>Single, compound, and optioned indexes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>· <a href="03_use_cases/14_testing_guide/">14 – Testing guide</a></td>
|
||||
<td>Mock Motor, engine, cache, transactions</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="04_best_practices/">Best Practices</a></td>
|
||||
<td>Recommended repo structure and patterns</td>
|
||||
<td>Layering, lifecycle, and gotchas</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="05_patterns/">Common Patterns</a></td>
|
||||
<td>Service layer, aggregation, soft deletes</td>
|
||||
<td>Service layer, aggregation, bulk ops</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="06_error_handling/">Error Handling</a></td>
|
||||
<td>Centralized error and exception management</td>
|
||||
<td>Library exceptions and FastAPI mapping</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="07_testing_example/">Testing</a></td>
|
||||
<td>Pytest configuration and fixtures</td>
|
||||
<td><a href="07_testing_example/">Testing Example</a></td>
|
||||
<td>Mock-based quickstart</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@@ -1094,10 +1157,10 @@ It standardizes repository patterns, async CRUD operations, and model management
|
||||
<ul>
|
||||
<li><strong>Source Code:</strong> <a href="https://git.aetoskia.com/aetos/mongo-ops">Gitea Repository</a></li>
|
||||
<li><strong>Internal PyPI:</strong> <a href="https://pip.aetoskia.com/simple/mongo-ops">pip.aetoskia.com/simple/mongo-ops</a></li>
|
||||
<li><strong>Drone CI:</strong> Auto-builds and publishes tagged releases.</li>
|
||||
<li><strong>Drone CI:</strong> Auto-builds and publishes tagged releases, gated on black / ruff / mypy / pytest.</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<p>© Aetoskia Internal — <code>mongo-ops</code> 0.1.4</p>
|
||||
<p>© Aetoskia Internal — <code>mongo-ops</code> 0.1.5</p>
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user