libTerm 0.1.5

No project description provided

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:

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:

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):

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):

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

2. Build a distribution:

python -m pip install -U build
python -m build

3. Upload to PyPI (if intended):

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.