| Name | jinpy-utils JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | jinpy-utils is a collection of minimal, type-safe Python utilities for Caching, Logging, Settings, and ORM. It follows modern Python practices (PEP 8, mypy, Ruff) and maintains high test coverage. |
| upload_time | 2025-08-15 06:21:19 |
| maintainer | None |
| docs_url | None |
| author | Jinto A G |
| requires_python | >=3.12.10 |
| license | MIT |
| keywords |
python
utilities
caching
logging
settings
orm
asyncio
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# jinpy-utils
> Status: dev (dev-releases). Latest version badges above are dynamic.
Minimal, type-safe utilities for **Caching**, **Logging**, **Settings**, and **ORM**. Built with modern Python practices (PEP 8, mypy, ruff) and high test coverage. This is an early release; APIs may evolve.
📚 Docs: See the documentation in [docs/](https://github.com/jinto-ag/jinpy-utils/tree/main/docs) (start with [overview.md](docs/overview.md)).
## Features
- **🚀 Caching**: Advanced caching utilities with multiple backends
- **📝 Logging**: Structured logging with configurable console/file/REST/WebSocket backends
- **⚙️ Settings**: Configuration management with environment variable support
- **🗄️ ORM**: Database operations and migrations with SQLModel integration
- **✅ Type Safe**: Full type hints and mypy compatibility
- **🧪 Well Tested**: Comprehensive test coverage with pytest
- **🔧 Developer Friendly**: Pre-commit hooks and code quality tools
## Requirements
- **Python**: 3.12 or higher
- **Package Manager**: [uv](https://github.com/astral-sh/uv) (recommended)
## Installation
### Using uv (Recommended)
```bash
uv add jinpy-utils
```
### Using pip
```bash
pip install jinpy-utils
```
## Quick Start (Logging)
```python
from jinpy_utils.logger.config import GlobalLoggerConfig, ConsoleBackendConfig
from jinpy_utils.logger.core import Logger
# 1) Configure once (12-factor friendly; env helpers available)
cfg = GlobalLoggerConfig(backends=[ConsoleBackendConfig(name="console")])
Logger.set_global_config(cfg)
# 2) Get a logger and log
log = Logger.get_logger("app")
log.info("hello", {"env": "dev"})
```
## Core Dependencies
This library is built on top of these excellent packages:
- **[Pydantic](https://docs.pydantic.dev/latest/)** (v2+): Data validation and settings management
- **[SQLModel](https://sqlmodel.tiangolo.com/)** (v0.0.24+): SQL databases with Python type hints
- **[Structlog](https://www.structlog.org/)** (v24+): Structured logging
- **[Cachetools](https://cachetools.readthedocs.io/)** (v5+): Caching utilities
- **[Alembic](https://alembic.sqlalchemy.org/)** (v1.13+): Database migrations
- **[Python-dotenv](https://saurabh-kumar.com/python-dotenv/)** (v1+): Environment variables
## Development
### Prerequisites
- Python 3.12+
- [uv](https://github.com/astral-sh/uv) package manager
### Setup Development Environment
1. **Clone the repository**
```bash
git clone <repository-url>
cd jinpy-utils
```
2. **Install dependencies**
```bash
uv sync --all-extras
```
3. **Install pre-commit hooks**
```bash
uv run pre-commit install
```
### Commands
- Format code: `uv run ruff format .`
- Lint and fix issues: `uv run ruff check --fix .`
- Type checking: `uv run mypy .`
- Run tests: `uv run pytest`
- Run tests with coverage: `uv run pytest`
- Security scanning: `uv run bandit -r jinpy_utils`
- Run all pre-commit hooks: `uv run pre-commit run --all-files`
## Code Quality
This project maintains high code quality standards:
- **Code Formatting**: [Black](https://black.readthedocs.io/)
- **Linting**: [Ruff](https://docs.astral.sh/ruff/)
- **Type Checking**: [MyPy](https://mypy-lang.org/) with strict configuration
- **Security**: [Bandit](https://bandit.readthedocs.io/) for security issue detection
- **Testing**: [Pytest](https://docs.pytest.org/) with coverage reporting
- **Pre-commit Hooks**: Automated quality checks before commits
## Project Structure (partial)
```txt
jinpy-utils/
├── src/
│ └── jinpy_utils/ # Main package directory
│ ├── __init__.py
│ └── py.typed # Type information marker
├── tests/ # Test suite
├── docs/ # Documentation (coming soon)
├── pyproject.toml # Project configuration
├── README.md # This file
└── .pre-commit-config.yaml # Pre-commit configuration
```
## Contributing
We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for details on:
- Code style and standards
- Testing requirements
- Pull request process
- Issue reporting
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and quality checks
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## Roadmap (high-level)
- [ ] Core caching implementations
- [ ] Structured logging utilities
- [ ] Settings management system
- [ ] ORM helpers and utilities
- [ ] Comprehensive documentation
- [ ] Performance benchmarks
- [ ] Plugin system
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
**Jinto A G**
- Email: [project.jintoag@gmail.com](mailto:project.jintoag@gmail.com)
- GitHub: [jintoag](https://github.com/jinto-ag)
## Support
If you encounter any issues or have questions:
1. Check the [issues](https://github.com/jinto-ag/jinpy-utils/issues) page
2. Create a new issue with detailed information
3. Contact the maintainer via email
---
**Made with ❤️ and Python**
Raw data
{
"_id": null,
"home_page": null,
"name": "jinpy-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12.10",
"maintainer_email": null,
"keywords": "python, utilities, caching, logging, settings, orm, asyncio",
"author": "Jinto A G",
"author_email": "Jinto A G <project.jintoag@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2c/c9/837a274003e39a3b85ad3723f74097c34c512354042ad6c4b22ad3af24f0/jinpy_utils-0.2.0.tar.gz",
"platform": null,
"description": "# jinpy-utils\n\n\n\n\n\n\n\n> Status: dev (dev-releases). Latest version badges above are dynamic.\n\nMinimal, type-safe utilities for **Caching**, **Logging**, **Settings**, and **ORM**. Built with modern Python practices (PEP\u202f8, mypy, ruff) and high test coverage. This is an early release; APIs may evolve.\n\n\ud83d\udcda Docs: See the documentation in [docs/](https://github.com/jinto-ag/jinpy-utils/tree/main/docs) (start with [overview.md](docs/overview.md)).\n\n## Features\n\n- **\ud83d\ude80 Caching**: Advanced caching utilities with multiple backends\n- **\ud83d\udcdd Logging**: Structured logging with configurable console/file/REST/WebSocket backends\n- **\u2699\ufe0f Settings**: Configuration management with environment variable support\n- **\ud83d\uddc4\ufe0f ORM**: Database operations and migrations with SQLModel integration\n- **\u2705 Type Safe**: Full type hints and mypy compatibility\n- **\ud83e\uddea Well Tested**: Comprehensive test coverage with pytest\n- **\ud83d\udd27 Developer Friendly**: Pre-commit hooks and code quality tools\n\n## Requirements\n\n- **Python**: 3.12 or higher\n- **Package Manager**: [uv](https://github.com/astral-sh/uv) (recommended)\n\n## Installation\n\n### Using uv (Recommended)\n\n```bash\nuv add jinpy-utils\n```\n\n### Using pip\n\n```bash\npip install jinpy-utils\n```\n\n## Quick Start (Logging)\n\n```python\nfrom jinpy_utils.logger.config import GlobalLoggerConfig, ConsoleBackendConfig\nfrom jinpy_utils.logger.core import Logger\n\n# 1) Configure once (12-factor friendly; env helpers available)\ncfg = GlobalLoggerConfig(backends=[ConsoleBackendConfig(name=\"console\")])\nLogger.set_global_config(cfg)\n\n# 2) Get a logger and log\nlog = Logger.get_logger(\"app\")\nlog.info(\"hello\", {\"env\": \"dev\"})\n```\n\n## Core Dependencies\n\nThis library is built on top of these excellent packages:\n\n- **[Pydantic](https://docs.pydantic.dev/latest/)** (v2+): Data validation and settings management\n- **[SQLModel](https://sqlmodel.tiangolo.com/)** (v0.0.24+): SQL databases with Python type hints\n- **[Structlog](https://www.structlog.org/)** (v24+): Structured logging\n- **[Cachetools](https://cachetools.readthedocs.io/)** (v5+): Caching utilities\n- **[Alembic](https://alembic.sqlalchemy.org/)** (v1.13+): Database migrations\n- **[Python-dotenv](https://saurabh-kumar.com/python-dotenv/)** (v1+): Environment variables\n\n## Development\n\n### Prerequisites\n\n- Python 3.12+\n- [uv](https://github.com/astral-sh/uv) package manager\n\n### Setup Development Environment\n\n1. **Clone the repository**\n\n ```bash\n git clone <repository-url>\n cd jinpy-utils\n ```\n\n2. **Install dependencies**\n\n ```bash\n uv sync --all-extras\n ```\n\n3. **Install pre-commit hooks**\n\n ```bash\n uv run pre-commit install\n ```\n\n### Commands\n\n- Format code: `uv run ruff format .`\n- Lint and fix issues: `uv run ruff check --fix .`\n- Type checking: `uv run mypy .`\n- Run tests: `uv run pytest`\n- Run tests with coverage: `uv run pytest`\n- Security scanning: `uv run bandit -r jinpy_utils`\n- Run all pre-commit hooks: `uv run pre-commit run --all-files`\n\n## Code Quality\n\nThis project maintains high code quality standards:\n\n- **Code Formatting**: [Black](https://black.readthedocs.io/)\n- **Linting**: [Ruff](https://docs.astral.sh/ruff/)\n- **Type Checking**: [MyPy](https://mypy-lang.org/) with strict configuration\n- **Security**: [Bandit](https://bandit.readthedocs.io/) for security issue detection\n- **Testing**: [Pytest](https://docs.pytest.org/) with coverage reporting\n- **Pre-commit Hooks**: Automated quality checks before commits\n\n## Project Structure (partial)\n\n```txt\njinpy-utils/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 jinpy_utils/ # Main package directory\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 py.typed # Type information marker\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 docs/ # Documentation (coming soon)\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 .pre-commit-config.yaml # Pre-commit configuration\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for details on:\n\n- Code style and standards\n- Testing requirements\n- Pull request process\n- Issue reporting\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests and quality checks\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## Roadmap (high-level)\n\n- [ ] Core caching implementations\n- [ ] Structured logging utilities\n- [ ] Settings management system\n- [ ] ORM helpers and utilities\n- [ ] Comprehensive documentation\n- [ ] Performance benchmarks\n- [ ] Plugin system\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Jinto A G**\n\n- Email: [project.jintoag@gmail.com](mailto:project.jintoag@gmail.com)\n- GitHub: [jintoag](https://github.com/jinto-ag)\n\n## Support\n\nIf you encounter any issues or have questions:\n\n1. Check the [issues](https://github.com/jinto-ag/jinpy-utils/issues) page\n2. Create a new issue with detailed information\n3. Contact the maintainer via email\n\n---\n\n**Made with \u2764\ufe0f and Python**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "jinpy-utils is a collection of minimal, type-safe Python utilities for Caching, Logging, Settings, and ORM. It follows modern Python practices (PEP 8, mypy, Ruff) and maintains high test coverage.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/jinto-ag/jinpy-utils",
"Issues": "https://github.com/jinto-ag/jinpy-utils/issues",
"License": "https://github.com/jinto-ag/jinpy-utils/blob/main/LICENSE",
"Repository": "https://github.com/jinto-ag/jinpy-utils"
},
"split_keywords": [
"python",
" utilities",
" caching",
" logging",
" settings",
" orm",
" asyncio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "512cee829fbd32cb6ef84502ed05b27a2f6fbd49a4a81ba6e033be90105f9701",
"md5": "c3e486e20d7b7a6f7e7e601f1a1e09c8",
"sha256": "04beb623f6ad7e9ddf20315cf5684b704704e26db3a912c1f193c977e9bf90ab"
},
"downloads": -1,
"filename": "jinpy_utils-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3e486e20d7b7a6f7e7e601f1a1e09c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12.10",
"size": 44965,
"upload_time": "2025-08-15T06:21:17",
"upload_time_iso_8601": "2025-08-15T06:21:17.939936Z",
"url": "https://files.pythonhosted.org/packages/51/2c/ee829fbd32cb6ef84502ed05b27a2f6fbd49a4a81ba6e033be90105f9701/jinpy_utils-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2cc9837a274003e39a3b85ad3723f74097c34c512354042ad6c4b22ad3af24f0",
"md5": "7366c7ab7e627a4524c13b9a8ae41c06",
"sha256": "3239fd57defb8573a51e9dd3184e9bbd5c4606acff843b56591795cf60229613"
},
"downloads": -1,
"filename": "jinpy_utils-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7366c7ab7e627a4524c13b9a8ae41c06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12.10",
"size": 39789,
"upload_time": "2025-08-15T06:21:19",
"upload_time_iso_8601": "2025-08-15T06:21:19.511224Z",
"url": "https://files.pythonhosted.org/packages/2c/c9/837a274003e39a3b85ad3723f74097c34c512354042ad6c4b22ad3af24f0/jinpy_utils-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 06:21:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jinto-ag",
"github_project": "jinpy-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jinpy-utils"
}
