pykit3

Collection of Python 3 utility modules.

Module	Description
k3color	Terminal text coloring
k3confloader	Configuration loader
k3dict	Dictionary operations
k3down2	Markdown to media converter
k3fmt	String formatting utilities
k3fs	File system utilities
k3git	Git command wrapper
k3handy	Common function aliases
k3heap	Binary min heap
k3jobq	Concurrent job processor
k3log	Logging utilities
k3math	Math implementations
k3net	Network utilities
k3num	Human-readable numbers
k3pattern	Pattern matching
k3portlock	TCP port-based locks
k3priorityqueue	Priority queue
k3proc	Process utilities
k3rangeset	Range operations
k3shell	Shell command management
k3str	String utilities
k3thread	Thread utilities
k3time	Time conversion
k3txutil	Transaction helpers
k3ut	Unit test utilities

This repository manages the pykit3 module collection.

Development

Engineering Principles

• Clarity first: Write code for humans, prioritize readability
• Correctness over performance: Focus on getting it right first
• Simplicity: Throw away what can't be done in a day, rewrite simpler tomorrow
• No smart code: Write straightforward, maintainable code
• Comment WHY, not HOW: Let code explain itself

Workflow

1. Fork repository
2. Create feature branch
3. Implement changes
4. Open pull request with rebase to main

Module Development

Setup

• CI: GitHub Actions (.github/workflows/python-package.yml)
• Testing: pytest framework
• Documentation: Sphinx with Google docstring style
• Build docs: make doc

Module Structure

• __init__.py must define __name__ and __version__ (semantic versioning)
• GitHub metadata managed via .github/settings.yml

Publishing

1. Update __version__ in __init__.py
2. Commit and run make build_setup_py
3. Push tag to trigger PyPI upload via GitHub Actions

Directory Structure

k3module/
├── .github/workflows/    # CI/CD configurations
├── _building/           # Build utilities  
├── docs/               # Sphinx documentation
├── test/               # Unit tests
├── __init__.py        # Module metadata and exports
├── main_module.py     # Primary implementation
├── LICENSE
├── Makefile          # Build commands
├── README.md         # Auto-generated, do not edit
├── requirements.txt  # Dependencies
└── setup.py         # Auto-generated for releases

Key files:

• docs/source/index.rst: Update for new APIs
• README.md: Generated via make readme
• setup.py: Generated via make build_setup_py

Creating New Modules

1. Fork from tmpl (template repository)
2. Choose name starting with k3
3. Clone: git clone git@github.com:pykit3/k3newmodule.git
4. Generate skeleton: python ./_building/populate.py

Template Updates

• Populate it: python ./_building/populate.py. This step generates a skeleton of a module:

  python ./_building/populate.py
  git status
  ...
      new file：   .github/settings.yml
      new file：   __init__.py
      new file：   docs/source/index.rst
      new file：   package.json
      new file：   packages.txt
      new file：   requirements.txt
      new file：   test-requirements.txt
      new file：   test/test_doctest.py
      new file：   test/test_k3whatever.py
  

  Examine the generated files and add them and make your first commit!

Update tmpl changes

applytmpl.sh copies changes from repo tmpl to current dir. It should be run in a repo dir, e.g., k3zkutil:

./tmpl
./k3zkutil

To apply tmlp chagnes to every repo:

run-script-in-repos.sh repo-apply-tmpl.sh

Documentation & Testing

• Document all modules, classes, and methods
• Write comprehensive tests