Metadata-Version: 2.4
Name: astrobasis
Version: 0.1.0
Summary: Pure mechanism layer for the Astro ecosystem — zero hard dependencies
Author-email: Etoileint <etoileint@163.com>, Etoileint <littlestar@buaa.edu.cn>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Etoileint/AstroProject
Project-URL: Repository, https://github.com/Etoileint/AstroProject
Project-URL: Issues, https://github.com/Etoileint/AstroProject/issues
Project-URL: Documentation, https://github.com/Etoileint/AstroProject#readme
Keywords: logging,logfmt,structured-logging,atomic-write,json,orjson,protocol,async,mechanism,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: fast
Requires-Dist: orjson>=3.8; extra == "fast"
Dynamic: license-file

# astrobasis <em>天枢</em>

Pure mechanism layer for the Astro ecosystem. Zero hard dependencies beyond Python 3.12 stdlib.

## Install

```bash
pip install astrobasis
```

For JSON performance acceleration:

```bash
pip install astrobasis[fast]
```

Or from source:

```bash
pip install -e .
```

## What's inside

| Module | Purpose |
|--------|---------|
| `_logging` | Structured logfmt logging — mandatory event field, key=value output |
| `_atomic` | POSIX atomic file writes — mkstemp → fsync → os.replace |
| `_json_compat` | orjson / stdlib json compatibility layer with graceful fallback |
| `_types` | Shared protocols — `AsyncCloseable` for async resource lifecycle |

## Usage

### Structured logging

```python
from astrobasis import LogfmtLogger

logger = LogfmtLogger("my_module")
logger.info("request_complete", url="https://example.com", status=200)
# → ts=2026-07-17T... level=INFO logger=my_module event=request_complete url=https://example.com status=200
```

### Atomic file writes

```python
from astrobasis import atomic_write_json

data = {"key": "value", "nested": [1, 2, 3]}
atomic_write_json("/path/to/config.json", data)
# POSIX atomic: write to temp → fsync → os.replace. Concurrent reads always see complete data.
```

### JSON compatibility

```python
from astrobasis import _json_dumps

data = {"items": ["a", "b", "c"]}
result = _json_dumps(data)
# Uses orjson if installed (`pip install astrobasis[fast]`), stdlib json otherwise.
```

### Async resource protocol

```python
from astrobasis import AsyncCloseable

class MyResource(AsyncCloseable):
    async def aclose(self) -> None:
        await self._client.close()
```

## License

Apache 2.0
