Metadata-Version: 2.4
Name: rkivln
Version: 0.1.1
Summary: Developer utility toolkit for file, JSON, system, and project helpers.
Project-URL: Homepage, https://github.com/rkivln/rkivln-package
Project-URL: Repository, https://github.com/rkivln/rkivln-package
Project-URL: Bug Tracker, https://github.com/rkivln/rkivln-package/issues
Author-email: Gokulan <gokulan.rkivln@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,developer-tools,files,json,utilities
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: memory
Requires-Dist: psutil>=5.9; extra == 'memory'
Description-Content-Type: text/markdown

# rkivln

[![PyPI version](https://img.shields.io/pypi/v/rkivln.svg)](https://pypi.org/project/rkivln/)
[![Python](https://img.shields.io/pypi/pyversions/rkivln.svg)](https://pypi.org/project/rkivln/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://github.com/rkivln/rkivln-package/actions/workflows/test.yml/badge.svg)](https://github.com/rkivln/rkivln-package/actions)

A lightweight developer utility toolkit. File helpers, JSON tools, system info, and project scaffolding - all from a clean Python API and a single CLI.

---

## Install

```bash
pip install rkivln
```

For memory statistics (optional):

```bash
pip install "rkivln[memory]"
```

---

## Quick start

```python
import rkivln

# Package version
print(rkivln.__version__)

# System snapshot
info = rkivln.get_system_info()
print(info["python_version"])
print(info["platform"])
```

---

## Python API

### File utilities

```python
from rkivln import list_files, get_file_size, get_file_extension, find_files

# List all .py files recursively
files = list_files("./src", recursive=True, extensions=[".py"])

# File size in bytes
size = get_file_size("pyproject.toml")

# Extension
ext = get_file_extension("README.md")   # ".md"

# Glob search
hits = find_files(".", "*.json", recursive=True)
```

### JSON utilities

```python
from rkivln import load_json, save_json, validate_json, pretty_json

data = load_json("config.json")

save_json({"version": "0.1.0"}, "config.json")

is_valid = validate_json("config.json")   # True / False

print(pretty_json({"a": 1, "b": [1, 2, 3]}))
```

### System utilities

```python
from rkivln import get_system_info, get_python_version, get_platform, get_memory_info

info = get_system_info()
# {
#   "python_version": "3.11.4",
#   "platform": "linux",
#   "architecture": "x86_64",
#   "hostname": "...",
#   "memory": {"total": ..., "available": ..., "used": ..., "percent": ...}
# }

print(get_python_version())   # "3.11.4"
print(get_platform())         # "Linux-6.1.0-x86_64-with-glibc2.35"

mem = get_memory_info()       # requires pip install rkivln[memory]
```

### Project scaffolding

```python
from rkivln import create_project, create_python_project, create_gitignore
from pathlib import Path

# Minimal project (README + .gitignore)
root = create_project("my-tool", parent="~/projects")

# Full Python package layout
root = create_python_project("my-pkg")
# Creates:
#   my-pkg/
#   |-- src/my_pkg/__init__.py
#   |-- tests/__init__.py
#   |-- pyproject.toml
#   |-- README.md
#   `-- .gitignore

# Just a .gitignore
create_gitignore("./my-project", kind="python")   # or kind="generic"
```

### Exceptions

```python
from rkivln.exceptions import RkivlnError, RkivlnFileError, RkivlnJSONError, RkivlnProjectError

try:
    data = rkivln.load_json("missing.json")
except RkivlnFileError as e:
    print(f"File problem: {e}")
except RkivlnJSONError as e:
    print(f"JSON problem: {e}")
```

---

## CLI

```bash
# Start the CLI
rkivln

# Universal fallback
python -m rkivln

# Help
rkivln --help
rkivln --version

# System info (JSON output)
rkivln info

# List files
rkivln files ./src
rkivln files ./src --recursive --ext .py --ext .toml

# Validate / pretty-print JSON
rkivln json config.json
rkivln json config.json --validate-only

# Scaffold a Python project
rkivln init my-new-project
rkivln init my-new-project --output ~/projects
```

---

## Features

- **Zero required dependencies** - everything uses the Python standard library
- **File tools** - list, search, size, extension helpers
- **JSON tools** - load, save, validate, pretty-print with proper error handling
- **System info** - Python version, platform, architecture, memory (optional)
- **Project scaffolding** - generate modern `src/` layout projects in one command
- **Custom exceptions** - no silent failures, always a meaningful error
- **Full type hints** - works well with mypy and pyright
- **pytest test suite** - meaningful coverage across all modules
- **CLI** - argparse-based, no extra dependencies

---

## Project structure

```
rkivln-package/
|-- src/
|   `-- rkivln/
|       |-- __init__.py      # public API
|       |-- cli.py           # CLI entry point
|       |-- exceptions.py    # custom exceptions
|       |-- file_utils.py    # file helpers
|       |-- json_utils.py    # JSON helpers
|       |-- system.py        # system info
|       `-- project.py       # scaffolding
|-- tests/
|   |-- test_cli.py
|   |-- test_file_utils.py
|   |-- test_json_utils.py
|   |-- test_project.py
|   `-- test_system.py
|-- .github/workflows/
|   |-- test.yml
|   `-- publish.yml
|-- pyproject.toml
|-- README.md
|-- CHANGELOG.md
`-- LICENSE
```

---

## Development

```bash
git clone https://github.com/rkivln/rkivln-package.git
cd rkivln-package
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
```

To test the package from a local checkout before publishing:

```bash
python -m pip install .
python -m rkivln
```

### Run tests

```bash
pytest
pytest --cov=rkivln --cov-report=term-missing
```

---

## Publishing

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full publishing workflow.

---

## Versioning

This project follows [Semantic Versioning](https://semver.org/):

- **PATCH** (`0.1.x`) - bug fixes, no API changes
- **MINOR** (`0.x.0`) - new backwards-compatible features
- **MAJOR** (`x.0.0`) - breaking changes

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## License

[MIT](LICENSE) (c) Gokulan

---

## Author

**Gokulan** - [@rkivln](https://github.com/rkivln)
