python-mapper 0.3.0__tar.gz → 0.3.1__tar.gz

{python_mapper-0.3.0/src/python_mapper.egg-info → python_mapper-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mapper
-Version: 0.3.0
+Version: 0.3.1
 Summary: PostgreSQL XML mapper with asyncpg pooling and implicit transactions
 Author: z77777777777
 License-Expression: MIT
@@ -29,20 +29,55 @@ Dynamic: license-file
 
 # python-mapper
 
-[English](README.md) · [简体中文](README.zh-CN.md)
+[English](https://github.com/z77777777777/python-mapper/blob/main/README.md) ·
+[简体中文](https://github.com/z77777777777/python-mapper/blob/main/README.zh-CN.md)
 
-PostgreSQL-first XML mapper runtime backed directly by asyncpg. The package is
-framework-neutral: it does not import FastAPI, a host application's settings,
-logging formatter, schema, or business models.
+A lightweight asynchronous XML mapper for Python. It keeps SQL out of business code —
+queries live in XML, Python keeps only the signature — so a service method reads as what
+the business does, not as string assembly around a cursor.
+
+PostgreSQL-first, backed directly by asyncpg. The package is framework-neutral: it does
+not import FastAPI, a host application's settings, logging formatter, schema, or business
+models.
 
 ## Installation
 
 ```bash
-pip install "git+https://github.com/z77777777777/python-mapper.git@v0.3.0"
+pip install python-mapper
 ```
 
 Requires Python 3.12+. The only runtime dependencies are `asyncpg` and `Jinja2`.
 
+## Async only
+
+Every execution path is asynchronous. Mapper calls, `query()` and `scalar()` return
+coroutines, and `transactional()` raises `TypeError` at decoration time if handed a
+synchronous function. This is not an omission — the driver underneath is asyncpg, which
+has no synchronous API at all.
+
+To use it from a synchronous framework (Flask, a classic Django view, a script), run one
+long-lived event loop in a background thread and submit work to it:
+
+```python
+import asyncio
+import threading
+
+loop = asyncio.new_event_loop()
+threading.Thread(target=loop.run_forever, daemon=True).start()
+
+# Open the pool once, on that loop.
+asyncio.run_coroutine_threadsafe(open_database(...), loop).result()
+
+# Then, from synchronous code:
+rows = asyncio.run_coroutine_threadsafe(
+    OrdersMapper.find(order_id=1), loop,
+).result()
+```
+
+Do **not** wrap individual calls in `asyncio.run()`. That builds a fresh event loop every
+time, while an asyncpg pool stays bound to the loop that created it — you would either hit
+"attached to a different loop" errors or rebuild the pool on every request.
+
 ## Package layout
 
 - `database.py`: asyncpg pool configuration, startup, shutdown, and connection checkout.

{python_mapper-0.3.0 → python_mapper-0.3.1}/README.md

@@ -1,19 +1,54 @@
 # python-mapper
 
-[English](README.md) · [简体中文](README.zh-CN.md)
+[English](https://github.com/z77777777777/python-mapper/blob/main/README.md) ·
+[简体中文](https://github.com/z77777777777/python-mapper/blob/main/README.zh-CN.md)
 
-PostgreSQL-first XML mapper runtime backed directly by asyncpg. The package is
-framework-neutral: it does not import FastAPI, a host application's settings,
-logging formatter, schema, or business models.
+A lightweight asynchronous XML mapper for Python. It keeps SQL out of business code —
+queries live in XML, Python keeps only the signature — so a service method reads as what
+the business does, not as string assembly around a cursor.
+
+PostgreSQL-first, backed directly by asyncpg. The package is framework-neutral: it does
+not import FastAPI, a host application's settings, logging formatter, schema, or business
+models.
 
 ## Installation
 
 ```bash
-pip install "git+https://github.com/z77777777777/python-mapper.git@v0.3.0"
+pip install python-mapper
 ```
 
 Requires Python 3.12+. The only runtime dependencies are `asyncpg` and `Jinja2`.
 
+## Async only
+
+Every execution path is asynchronous. Mapper calls, `query()` and `scalar()` return
+coroutines, and `transactional()` raises `TypeError` at decoration time if handed a
+synchronous function. This is not an omission — the driver underneath is asyncpg, which
+has no synchronous API at all.
+
+To use it from a synchronous framework (Flask, a classic Django view, a script), run one
+long-lived event loop in a background thread and submit work to it:
+
+```python
+import asyncio
+import threading
+
+loop = asyncio.new_event_loop()
+threading.Thread(target=loop.run_forever, daemon=True).start()
+
+# Open the pool once, on that loop.
+asyncio.run_coroutine_threadsafe(open_database(...), loop).result()
+
+# Then, from synchronous code:
+rows = asyncio.run_coroutine_threadsafe(
+    OrdersMapper.find(order_id=1), loop,
+).result()
+```
+
+Do **not** wrap individual calls in `asyncio.run()`. That builds a fresh event loop every
+time, while an asyncpg pool stays bound to the loop that created it — you would either hit
+"attached to a different loop" errors or rebuild the pool on every request.
+
 ## Package layout
 
 - `database.py`: asyncpg pool configuration, startup, shutdown, and connection checkout.

{python_mapper-0.3.0 → python_mapper-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-mapper"
-version = "0.3.0"
+version = "0.3.1"
 description = "PostgreSQL XML mapper with asyncpg pooling and implicit transactions"
 readme = "README.md"
 requires-python = ">=3.12"

{python_mapper-0.3.0 → python_mapper-0.3.1/src/python_mapper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mapper
-Version: 0.3.0
+Version: 0.3.1
 Summary: PostgreSQL XML mapper with asyncpg pooling and implicit transactions
 Author: z77777777777
 License-Expression: MIT
@@ -29,20 +29,55 @@ Dynamic: license-file
 
 # python-mapper
 
-[English](README.md) · [简体中文](README.zh-CN.md)
+[English](https://github.com/z77777777777/python-mapper/blob/main/README.md) ·
+[简体中文](https://github.com/z77777777777/python-mapper/blob/main/README.zh-CN.md)
 
-PostgreSQL-first XML mapper runtime backed directly by asyncpg. The package is
-framework-neutral: it does not import FastAPI, a host application's settings,
-logging formatter, schema, or business models.
+A lightweight asynchronous XML mapper for Python. It keeps SQL out of business code —
+queries live in XML, Python keeps only the signature — so a service method reads as what
+the business does, not as string assembly around a cursor.
+
+PostgreSQL-first, backed directly by asyncpg. The package is framework-neutral: it does
+not import FastAPI, a host application's settings, logging formatter, schema, or business
+models.
 
 ## Installation
 
 ```bash
-pip install "git+https://github.com/z77777777777/python-mapper.git@v0.3.0"
+pip install python-mapper
 ```
 
 Requires Python 3.12+. The only runtime dependencies are `asyncpg` and `Jinja2`.
 
+## Async only
+
+Every execution path is asynchronous. Mapper calls, `query()` and `scalar()` return
+coroutines, and `transactional()` raises `TypeError` at decoration time if handed a
+synchronous function. This is not an omission — the driver underneath is asyncpg, which
+has no synchronous API at all.
+
+To use it from a synchronous framework (Flask, a classic Django view, a script), run one
+long-lived event loop in a background thread and submit work to it:
+
+```python
+import asyncio
+import threading
+
+loop = asyncio.new_event_loop()
+threading.Thread(target=loop.run_forever, daemon=True).start()
+
+# Open the pool once, on that loop.
+asyncio.run_coroutine_threadsafe(open_database(...), loop).result()
+
+# Then, from synchronous code:
+rows = asyncio.run_coroutine_threadsafe(
+    OrdersMapper.find(order_id=1), loop,
+).result()
+```
+
+Do **not** wrap individual calls in `asyncio.run()`. That builds a fresh event loop every
+time, while an asyncpg pool stays bound to the loop that created it — you would either hit
+"attached to a different loop" errors or rebuild the pool on every request.
+
 ## Package layout
 
 - `database.py`: asyncpg pool configuration, startup, shutdown, and connection checkout.