Cereja
Cereja is a Python utility package for developers who want reusable helpers for files, paths, progress display, compression, hashing, text processing, data preparation, arrays, dates, and small system tasks.
The package is published on PyPI and supports Python 3.11 and newer.
Design principles
- Zero runtime dependencies
- Standard-library-first implementations
- Small, reusable and composable APIs
- Backward compatibility where practical
- Educational implementations without hiding Python internals
Installation
python -m pip install cereja
Quick Start
import cereja as cj
path = cj.Path(".")
print(path.list_files())
from cereja.file import FileIO
file = FileIO.create("./example.txt", ["first line", "second line"])
file.add("third line")
file.save()
CLI
cereja --help
cereja tree .
cereja compress path/to/input
cereja decompress archive.cjz
Progress is enabled by default for CLI compression and decompression. Use --quiet for script-friendly output.
Bounded context search
Search for all whitespace-separated terms in UTF-8 text under one or more explicit roots:
cereja context search --root docs --query "context search" --extension md
cereja context search --root docs --root cereja --query "Path FileIO" --format json
Inventory text files without returning their content:
cereja context list --root docs --max-results 20
Use --max-file-bytes, --max-results, --max-snippets, and
--max-snippet-chars to bound search output. Searched source files are opened
read-only and are never modified. The commands decode only UTF-8 text, skip
binary files, and do not follow symbolic links.
The persistent cache is opt-in. When --cache is enabled, Cereja writes a
global per-user cache outside the searched roots. Use --cache to populate or
reuse it and --refresh-cache with --cache to force file content to be
reprocessed:
cereja context search --root docs --query "context search" --cache
cereja context search --root docs --query "context search" --cache --refresh-cache
Inspect cache metadata or clear the context-cache namespace with:
cereja context cache info --format json
cereja context cache clear
If the optional cache is unavailable, context search emits a
ContextCacheWarning and continues with a direct filesystem search.
Development
git clone https://github.com/cereja-project/cereja.git
cd cereja
python -m pip install -e .
python -m unittest discover -s tests -v
Run the syntax/undefined-name lint used by CI:
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
Documentation
- Documentation: https://cereja.readthedocs.io/
- Source code: https://github.com/cereja-project/cereja
- Issues: https://github.com/cereja-project/cereja/issues/new/choose
- PyPI: https://pypi.org/project/cereja/
- Examples notebook: docs/cereja_example.ipynb
Citation
If you use Cereja in academic work, please cite it. GitHub uses CITATION.cff for the "Cite this repository" button,
and a BibTeX entry is available in CITATION.bib.
License
Cereja is distributed under the MIT License. See LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for cereja 2.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cereja-2.3.0.tar.gz | 339.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cereja-2.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 655.9 kB
Release files / cereja-2.3.0.tar.gz
| Download URL | cereja-2.3.0.tar.gz |
|---|---|
| Size | 339.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f0cf1eca90113a0ea3f1289c01b0d47a968ac8dc2cfc0235ef33fb2676dab721
|
|
BLAKE2b-256 checksum How to use checksums |
475500737a8b9514c72058997563828ef4f79af627ae7430666801def9225d91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / cereja-2.3.0-py3-none-any.whl
| Download URL | cereja-2.3.0-py3-none-any.whl |
|---|---|
| Size | 316.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3afcbb3a88f3fa34b378b9cf9ada46ef8f8f69c4b2ce78b912751bf43b874998
|
|
BLAKE2b-256 checksum How to use checksums |
6ba93f11290c39af06546fb1e35143d4a5f4e88ca9c6a624919051dfd52ff8ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
