miu-logger 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

miu_logger-0.2.0.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: miu-logger
+Version: 0.2.0
+Summary: Multiprocessing-safe domain-based logging framework with QueueListener architecture
+Author-email: Bruno Miura <brumiura@gmail.com>
+License-Expression: MIT
+Keywords: logging,multiprocessing,queue,structured-logging,python-logging
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorama
+Dynamic: license-file
+
+# miu-logger
+
+**Multiprocessing-safe, domain-driven structured logging for Python services**
+
+`miu-logger` is a logging framework designed for **real systems**:
+
+* Multiprocessing- and multithreading-safe
+* Domain-separated loggers (`app`, `db`, `task`, etc.)
+* Per-level log files (`debug.log`, `info.log`, `error.log`, …)
+* Central queue listener to avoid file collisions
+* Clean IDE autocomplete for both domains and log levels
+* Minimal setup in application code
+
+---
+
+## Why use `miu-logger`
+
+Python's standard logging is powerful but breaks down when:
+
+* Multiple processes or threads write to the same log files
+* You want **domain-specific log files**
+* You want **centralized log routing**
+* You want IDE autocomplete for domains and levels
+
+`miu-logger` solves this by:
+
+> Logging through a **central queue listener**, separating **domains** and **levels**, while exposing a **typed repository** for IDE-friendly access.
+
+---
+
+## Installation
+
+```bash
+uv add miu-logger
+# or
+pip install miu-logger
+```
+
+---
+
+## Configuring Logging Domains
+
+Domains represent **areas of your system** (not log levels). Examples: `app`, `db`, `redis`, `task`.
+
+Define them in `LogConfig`:
+
+```python
+import logging
+from miu_logger.config import LogConfig
+from miu_logger.repository import LoggingRepository
+
+config = LogConfig(
+    log_dir="logs",                     # folder to store logs
+    domains=["app", "db", "redis"],     # your custom domains
+    level=logging.DEBUG,                # base log level for all domains
+    debug_enabled=True,                 # toggle debug messages
+)
+
+repo = LoggingRepository(config)
+```
+
+### Accessing Domain Loggers
+
+```python
+repo.app.info("Application started")
+repo.db.error("Database connection failed")
+repo.redis.debug("Cache initialized")
+```
+
+* Accessing a domain not defined in `config.domains` raises a `ValueError`:
+
+```python
+repo.get("api")  # ❌ ValueError if "api" not in config.domains
+```
+
+* Domains can also be dynamically retrieved:
+
+```python
+task_logger = repo.get("task")  # Must be defined in config.domains
+task_logger.info("Task started")
+```
+
+---
+
+## IDE Autocomplete with Stub Generation
+
+Domains are dynamic, so editors cannot know them automatically.
+Use the **stub generator** to enable autocomplete:
+
+```python
+from miu_logger.stubgen import generate_repository_stub
+
+generate_repository_stub(
+    domains=["app", "db", "redis", "task"],  # all your domains
+    out_dir="typings",                       # directory for generated stubs
+)
+```
+
+This creates:
+
+```
+typings/miu_logger/repository.pyi
+```
+
+Tell your editor where the typings are:
+
+* **VSCode / Pyright**:
+
+```json
+{
+  "python.analysis.extraPaths": ["typings"]
+}
+```
+
+* **pyproject.toml (Pyright)**:
+
+```toml
+[tool.pyright]
+extraPaths = ["typings"]
+```
+
+After this, your IDE knows both:
+
+* Domains: `repo.app`, `repo.db`, …
+* Log methods: `.debug()`, `.info()`, `.warning()`, `.error()`, `.exception()`
+
+Regenerate stubs whenever you add new domains.
+
+---
+
+## Multiprocessing Usage
+
+The repository uses a **central QueueListener** for safe multiprocessing logging.
+
+**Main process:**
+
+```python
+repo = LoggingRepository(config)
+queue = repo.get_queue()
+```
+
+**Worker processes:**
+
+```python
+worker_repo = LoggingRepository(config, use_listener=False, queue=queue)
+worker_repo.task.info("Worker started")
+```
+
+All processes log safely to the same listener and files.
+
+---
+
+## Debug Control
+
+Only `.debug()` messages are conditional via `debug_enabled`:
+
+```python
+config.debug_enabled = False
+repo.app.debug("Won't appear")
+repo.app.info("Will appear")
+```
+
+Useful for toggling debug messages in production.
+
+---
+
+## Output Structure
+
+Logs are written in:
+
+```
+logs/
+ ├─ app.log         # domain logs
+ ├─ db.log
+ ├─ redis.log
+ ├─ debug.log       # per-level logs
+ ├─ info.log
+ ├─ warning.log
+ └─ error.log
+```
+
+Console output is **colorized** by level:
+
+* DEBUG → blue
+* INFO → green
+* WARNING → yellow
+* ERROR → red
+
+Files remain clean.
+
+---
+
+## Graceful Shutdown
+
+The repository automatically shuts down on process exit and supports manual shutdown:
+
+```python
+repo.shutdown()
+```
+
+---
+
+## Typical Usage Example
+
+```python
+repo.app.info("Service starting")
+
+try:
+    connect_db()
+except Exception:
+    repo.db.exception("DB connection failed")
+
+repo.redis.debug("Cache size: %d", cache_size)
+```
+
+**Multiprocessing workers:**
+
+```python
+def worker(queue):
+    repo = LoggingRepository(config, use_listener=False, queue=queue)
+    repo.task.info("Worker task started")
+```
+
+---
+
+## Project Structure
+
+```
+miu_logger/
+ ├─ repository.py         # main LoggingRepository
+ ├─ listener.py           # QueueListener and handler setup
+ ├─ logger_factory.py     # logger creation functions
+ ├─ conditional.py        # ConditionalLogger
+ ├─ filters.py            # Logger filters
+ ├─ formatters.py         # ColoredFormatter
+ ├─ config.py             # LogConfig definition
+ └─ stubgen.py            # stub generator for IDE autocomplete
+```
+
+---
+
+## When to Use
+
+* Services with many subsystems
+* Multiprocessing ingestion pipelines
+* Long-running daemons
+* Kubernetes / systemd services
+* Need for clear operational logs
+
+---
+
+## When Not to Use
+
+* Single-file scripts
+* No multiprocessing
+* No domain separation required
+
+Plain `logging` is sufficient in those cases.
+
+---
+
+## License
+
+MIT
+
+---
+
+## Author
+
+**Bruno Miura**

{miu_logger-0.1.6.dist-info → miu_logger-0.2.0.dist-info}/RECORD

@@ -7,8 +7,8 @@ miu_logger/listener.py,sha256=K6JDf-R3VQx6t1zfNnh3ltJRnAyYdV5TFTAeWQqc6bU,3336
 miu_logger/logger_factory.py,sha256=MhNaP73J9RbhmmVR6simqkZRCel2g6rPImRlijYAQXI,319
 miu_logger/repository.py,sha256=FQOO-njKzW6i528EJpDYfusPDbW2DEGcVpxnqHUbzgg,2458
 miu_logger/stubgen.py,sha256=w0TJRu2aG55Gs1_tKwOcU7f7Nmr6j0l36rMgMHsz-SM,1878
-miu_logger-0.1.6.dist-info/licenses/LICENSE,sha256=jLLem0QFpsFv7Lkgp7I7FeN4DIdgCKIxzklfdkkesWg,1075
-miu_logger-0.1.6.dist-info/METADATA,sha256=ufZi24rFlglR7Cb5qaNBPA3D54f3JSgjUGlXnu2xoq8,2915
-miu_logger-0.1.6.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-miu_logger-0.1.6.dist-info/top_level.txt,sha256=70Nuj1YRYLMkqiRZv1pPZPhi_VystPGqm1nC3s-uHz4,11
-miu_logger-0.1.6.dist-info/RECORD,,
+miu_logger-0.2.0.dist-info/licenses/LICENSE,sha256=jLLem0QFpsFv7Lkgp7I7FeN4DIdgCKIxzklfdkkesWg,1075
+miu_logger-0.2.0.dist-info/METADATA,sha256=grikqmBJXT_Iqwd7V7mK70jlcm-w6J_AFffzJH0dN-M,6030
+miu_logger-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+miu_logger-0.2.0.dist-info/top_level.txt,sha256=70Nuj1YRYLMkqiRZv1pPZPhi_VystPGqm1nC3s-uHz4,11
+miu_logger-0.2.0.dist-info/RECORD,,

miu_logger-0.1.6.dist-info/METADATA

@@ -1,151 +0,0 @@
-Metadata-Version: 2.4
-Name: miu-logger
-Version: 0.1.6
-Summary: Multiprocessing-safe domain-based logging framework with QueueListener architecture
-Author-email: Bruno Miura <brumiura@gmail.com>
-License-Expression: MIT
-Keywords: logging,multiprocessing,queue,structured-logging,python-logging
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Operating System :: OS Independent
-Classifier: Topic :: System :: Logging
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: colorama
-Dynamic: license-file
-
-```python
-repo = LoggingRepository(config)
-queue = repo.get_queue()
-```
-
-**Worker processes:**
-
-```python
-worker_repo = LoggingRepository(config, use_listener=False, queue=queue)
-worker_repo.task.info("Worker started")
-```
-
-All processes log safely to the same listener and files.
-
----
-
-## Debug Control
-
-Only `.debug()` messages are conditional via `debug_enabled`:
-
-```python
-config.debug_enabled = False
-repo.app.debug("Won't appear")
-repo.app.info("Will appear")
-```
-
-Useful for toggling debug messages in production.
-
----
-
-## Output Structure
-
-Logs are written in:
-
-```
-logs/
- ├─ app.log         # domain logs
- ├─ db.log
- ├─ redis.log
- ├─ debug.log       # per-level logs
- ├─ info.log
- ├─ warning.log
- └─ error.log
-```
-
-Console output is **colorized** by level:
-
-* DEBUG → blue
-* INFO → green
-* WARNING → yellow
-* ERROR → red
-
-Files remain clean.
-
----
-
-## Graceful Shutdown
-
-The repository automatically shuts down on process exit and supports manual shutdown:
-
-```python
-repo.shutdown()
-```
-
----
-
-## Typical Usage Example
-
-```python
-repo.app.info("Service starting")
-
-try:
-    connect_db()
-except Exception:
-    repo.db.exception("DB connection failed")
-
-repo.redis.debug("Cache size: %d", cache_size)
-```
-
-**Multiprocessing workers:**
-
-```python
-def worker(queue):
-    repo = LoggingRepository(config, use_listener=False, queue=queue)
-    repo.task.info("Worker task started")
-```
-
----
-
-## Project Structure
-
-```
-miu_logger/
- ├─ repository.py         # main LoggingRepository
- ├─ listener.py           # QueueListener and handler setup
- ├─ logger_factory.py     # logger creation functions
- ├─ conditional.py        # ConditionalLogger
- ├─ filters.py            # Logger filters
- ├─ formatters.py         # ColoredFormatter
- ├─ config.py             # LogConfig definition
- └─ stubgen.py            # stub generator for IDE autocomplete
-```
-
----
-
-## When to Use
-
-* Services with many subsystems
-* Multiprocessing ingestion pipelines
-* Long-running daemons
-* Kubernetes / systemd services
-* Need for clear operational logs
-
----
-
-## When Not to Use
-
-* Single-file scripts
-* No multiprocessing
-* No domain separation required
-
-Plain `logging` is sufficient in those cases.
-
----
-
-## License
-
-MIT
-
----
-
-## Author
-
-**Bruno Miura**