README.coders

This file contains notes to coders who want to contribute to the project

#
# Code Style
#
The code must run under Python 3.9+

Follow the PEP 8 style guide. Use modern Python tooling for formatting:

# Format code
black src/compiletools/
# or
ruff format src/compiletools/

# Lint code  
ruff check src/compiletools/



#
# Running tests
#
The project uses pytest as its testing framework. First install development dependencies:

uv pip install -e ".[dev]"

Then run tests:

# Run all tests
pytest src/compiletools

# Run tests in parallel (faster)
pytest src/compiletools -n auto

# Run specific test file
pytest src/compiletools/test_utils.py

# Run with verbose output
pytest src/compiletools -v

#
# Test Style Guidelines
#
All tests should follow pytest conventions. Prefer function-based style over class-based:

# Preferred (function-based)
def test_something():
    assert my_function() == expected_result

# Acceptable (class-based for complex tests with shared setup)
class TestComplexFeature:
    def setup_method(self):
        # setup code
        
    def test_feature_behavior(self):
        assert feature.behavior() == expected

Simple tests with single test methods should use function-based style.
Use class-based style only when tests share complex setup/teardown logic.

#
# pytest Features and Best Practices
#
pytest provides powerful features for testing:

**Fixtures**: Use fixtures for reusable setup and teardown
def test_with_temp_dir(tmp_path):
    # tmp_path is a pytest built-in fixture providing temp directory
    test_file = tmp_path / "test.txt"
    test_file.write_text("content")
    assert test_file.exists()

**Parametrization**: Test multiple inputs with single test function
@pytest.mark.parametrize("input,expected", [
    (2, 4),
    (3, 9),
    (4, 16),
])
def test_square(input, expected):
    assert input ** 2 == expected

**Markers**: Mark tests for selective execution
@pytest.mark.slow
def test_slow_operation():
    # Run with: pytest -m "not slow" to skip slow tests
    pass

**Assertions**: Use simple assert statements
def test_equality():
    assert result == expected  # pytest provides detailed failure messages

**Mocking**: unittest.mock works seamlessly with pytest
from unittest.mock import Mock, patch

def test_with_mock():
    mock_obj = Mock(return_value=42)
    assert mock_obj() == 42

**Test Discovery**: pytest automatically discovers tests
- Files matching test_*.py or *_test.py
- Functions named test_*
- Classes named Test* with test_* methods

#
# Caches/Performance
#
When you are doing performance testing there are 3 caches you need to be aware of

1) ccache:  This can be cleaned by ccache -C
2) cake:    The default is for any caches to be kept in the bin directory.  rm -rf bin 
3) ct-*:    The default cache is supplied by the appdirs module.  
            So on linux that means the XDG user cache directory which defaults to $HOME/.cache/ct.  
                rm -rf ~/.cache/ct
            Note that it obeys the XDG variables.  Alter XDG_CACHE_HOME if you need to move the cache.
            ct-cache-clean will correctly remove the cache as specified by the XDG_CACHE_HOME
            It is possible to override the above by specifying the CTCACHE environment variable.
            CTCACHE=None turns off diskcaching

#
# Gotchas
#
If you encounter cache-related issues, clear the cache using:
ct-cache-clean

#
# Package Structure
#
src/compiletools/     - Main package code (moved from ct/)
ct-*                  - Command-line scripts  
pyproject.toml        - Modern Python packaging configuration
CLAUDE.md            - Project documentation and build instructions

#
# Development Setup
#
# Install development dependencies
uv pip install -e ".[dev]"

# or manually install dev tools
pip install bump-my-version twine

#
# Making a release
#
The ct-release script automates the release process, or you can do it manually:

# Increase the version number using bump-my-version
# Configuration is in pyproject.toml [tool.bumpversion] section
bump-my-version bump patch
# or
bump-my-version bump minor  
# or
bump-my-version bump major

git push
git push --tags

# Build and upload to PyPI
uv build
twine upload dist/* -r pypi

# Test installation
pip install compiletools