Metadata-Version: 2.4
Name: libTerm
Version: 0.1.0
Author-email: Jeroen Hoefkens <hoefkens.j@gmail.com>
Project-URL: Homepage, https://github.com/hoefkensj/libTerm
Project-URL: Issues, https://github.com/hoefkensj/Clict/libTerm
Description-Content-Type: text/markdown

# libTerm
## NOTE: this file(readme.md) was written by AI so i would not trust it for one bit...
## NOTE: tests were also generated by AI, same deal

A small, cross-platform Python utility library for terminal interaction and control.

libTerm provides a lightweight abstraction over terminal APIs for POSIX and Windows, exposing helpers for:

- querying and tracking terminal size
- reading and manipulating cursor position
- discovering terminal color settings
- entering basic terminal modes (raw/cbreak) on POSIX

The project uses a src-layout and aims to be minimal and easy to extend for CLI tools and terminal UI experiments.

---

## Quick links

- Source: `src/libTerm`
- POSIX implementation: `src/libTerm/term/posix.py`
- Windows implementation: `src/libTerm/term/winnt.py`
- Types & helpers: `src/libTerm/term/types.py`
- Cursor helpers: `src/libTerm/term/cursor.py`
- Tests: `tests/`
- Packaging metadata: `pyproject.toml`

---

## Status

This library is an early-stage utility package (version 0.0.1 in `pyproject.toml`). Some APIs are partial or defensive and a few implementation stubs exist (see `winnt.py` and `cursor.py`). Use in production after reviewing and adding tests for your use case.

---

## Install (development)

From the repository root you can install in editable mode for development:

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

This will make the `libTerm` package importable from your environment.

---

## Basic usage

The library exposes a `Term` object that delegates to a platform-specific implementation:

```python
from libTerm import Term

term = Term()
print("size:", term.size.rc)     # (cols, rows)
print("width:", term.size.width)
print("height:", term.size.height)

# Colors and cursor helpers are available under `term.color` and `term.cursor` on supported platforms
# Example (POSIX):
print(term.color.fg)  # dataclass with RGB values for foreground (may be None on some terminals)

# Term modes (POSIX):
term.mode('ctl')   # switch to non-canonical, no-echo mode (POSIX only)
term.mode('normal')
```

Note: Windows and POSIX code paths differ. Some methods are stubs on Windows; inspect `src/libTerm/term/winnt.py` before use.

---

## Project layout and "what goes where"

This repository follows a common Python "src" layout. Keep these rules in mind when contributing:

- `src/libTerm/` – the runtime package. All new package modules should live under here.
  - `src/libTerm/term/` – terminal-related implementation and platform layers. Add new terminal utilities here.
- `tests/` – unit and integration tests. Add pytest-compatible tests here. Import the package the same way end-users will: `from libTerm import Term`.
- `doc/` – longer documentation and design notes. Use `doc/dev/` for contributor-facing docs.
- `build/` – build artifacts (ignored by VCS for contributors). Do not commit build outputs unless intentional.
- `pyproject.toml` – project metadata and build-system. This project uses setuptools and setuptools-scm.

Files to update when changing public behavior:

- `pyproject.toml` — update the version or rely on tags (setuptools-scm).
- `PKG-INFO` / packaging metadata — will be generated by packaging tools.

---

## Naming conventions & coding practices

Follow these conventions to keep the codebase consistent and maintainable:

- Project and package name: `libTerm` (package root: `src/libTerm`).
- Modules should be snake_case (e.g. `cursor.py`, `types.py`, `posix.py`).
- Classes should use CapWords (PascalCase) and be exported from the package `__init__` only when part of the public API.
- Prefer small, focused modules. Keep platform-dependent code behind clear boundaries (see `term/__init__.py` which chooses implementation by `os.name`).
- Use dataclasses for small value types (the codebase already uses `@dataclass`).
- Avoid reading from stdin/stdout at import time. Prefer lazily reading when a method is called so the package can be imported safely in tests and tooling.
- Keep side effects (like registering atexit or writing to stdout) in initialization code that is explicit and documented.
- Add type hints when practical. The codebase mixes dynamic typing and dataclasses; use static typing gradually and keep tests updated.

---

## Tests

There is a minimal `tests/test.py` file. Contributing changes should include tests covering:

- POSIX behavior (can run on CI runners using linux/mac)
- Windows behavior (when adding or changing `winnt.py`) — use matrix CI with a Windows runner where possible

Run tests locally (recommended to use a virtualenv):

```bash
python -m pip install -U pytest
python -m pytest -q
```

Add tests under `tests/` with clear names and focused assertions. Use small, isolated tests for platform-specific code and avoid relying on interactive stdin in CI.

---

## Development workflow and contributing

Suggested developer workflow:

1. Fork the repository and create a feature branch from `main` (or master if available): `feature/your-short-description`.
2. Run the existing tests and linting locally.
3. Implement your change with small commits and add tests that demonstrate the fix/feature.
4. Update or add documentation in `doc/` if the public API changes.
5. Open a Pull Request describing the change, tests, and rationale.

Pull request checklist for contributors:

- [ ] Tests added/updated and pass locally
- [ ] Style checks (PEP8) applied
- [ ] Documentation updated where public behavior changes
- [ ] CI (if added) passes for target platforms

---

## Packaging & release

This project uses `setuptools` and `setuptools-scm` for versioning. Typical release steps:

1. Tag a release in git (for setuptools-scm to pick up version):

```bash
git tag -a vX.Y.Z -m "Release X.Y.Z"
git push --tags
```

2. Build a distribution:

```bash
python -m pip install -U build
python -m build
```

3. Upload to PyPI (if intended):

```bash
python -m pip install -U twine
python -m twine upload dist/*
```

Add CI workflows for automated builds and tests on push/PRs.

---

## Known gaps & TODOs

- Some methods are partial or stubbed (for example `vCursor.__update__` in `cursor.py`). Review and implement or document intended behavior before relying on them.
- Windows implementation (`winnt.py`) contains simplified code paths and stubs — test on real Windows terminals before assuming parity with POSIX.
- Interactive stdin parsing in `cursor.py` and `types.Colors._ansiparser_` reads from `sys.stdin` synchronously. This is fragile in automated environments and should be replaced with safer, testable parsers.
- Add a `LICENSE` file to clarify usage and contribution rights.

---

## Getting help

If you need help getting started, open an issue describing the platform and what you tried. Include `python --version` and OS details.

---

Thank you for contributing! Your patches, tests and documentation improvements are welcome.

