Project Structure Reorganization

[PPeitsch]

Project Structure Reorganization

Overview

This proposal aims to improve the Pkynetics library structure to enhance modularity, maintainability, and adherence to Python packaging best practices, with a focus on automation and quality assurance. The reorganization emphasizes better separation between theoretical methods and practical implementations, clear organization of technique-specific functionalities, and robust automation practices.

Current Issues

1. Mixed concerns in some modules:
   • Theoretical methods mixed with their implementations
   • Data preprocessing mixed with analysis logic
2. Inconsistent structure across similar components:
   • Different approaches for similar techniques
   • Inconsistent method signatures
3. Limited reusability of common functionality:
   • Duplicate code across techniques
   • Non-standardized base implementations
4. Potential code duplication across techniques:
   • Similar data processing routines
   • Common mathematical operations
5. Complex testing structure:
   • Difficult to maintain test coverage
   • Inconsistent test organization
6. Lack of automated quality controls:
   • Manual testing processes
   • Inconsistent code style
   • No automated deployment

Proposed Structure

src/pkynetics/
├── __init__.py
├── core/
│   ├── __init__.py
│   ├── base.py      # Abstract base classes
│   └── exceptions.py
├── data_import/
│   ├── __init__.py
│   ├── base.py
│   └── implementations/
│       ├── __init__.py
│       ├── tga.py
│       ├── dsc.py
│       └── dilatometry.py
├── data_preprocessing/
│   ├── __init__.py
│   ├── base.py
│   ├── filters.py
│   └── implementations/
│       ├── __init__.py
│       ├── tga.py
│       ├── dsc.py
│       └── dilatometry.py
├── kinetic_methods/
│   ├── __init__.py
│   ├── base.py
│   ├── model_fitting/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── methods/
│   │       ├── __init__.py
│   │       ├── avrami.py
│   │       ├── coats_redfern.py
│   │       ├── freeman_carroll.py
│   │       ├── horowitz_metzger.py
│   │       └── kissinger.py
│   ├── model_free/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── methods/
│   │       ├── __init__.py
│   │       ├── friedman.py
│   │       ├── ozawa_flynn_wall.py
│   │       └── kissinger_akahira_sunose.py
│   └── utils/
│       ├── __init__.py
│       ├── math.py
│       └── validation.py
├── technique_analysis/
│   ├── __init__.py
│   ├── base.py
│   ├── tga/
│   │   ├── __init__.py
│   │   ├── core.py
│   │   ├── analysis.py
│   │   └── methods/
│   │       ├── __init__.py
│   │       ├── single_step.py
│   │       └── multi_step.py
│   ├── dsc/
│   │   ├── __init__.py
│   │   ├── core.py
│   │   ├── analysis.py
│   │   └── methods/
│   │       ├── __init__.py
│   │       ├── crystallization.py
│   │       └── glass_transition.py
│   └── dilatometry/
│       ├── __init__.py
│       ├── core.py
│       ├── analysis.py
│       └── methods/
│           ├── __init__.py
│           ├── lever.py
│           └── tangent.py
└── visualization/
    ├── __init__.py
    ├── base.py
    ├── common.py
    └── technique/
        ├── __init__.py
        ├── tga.py
        ├── dsc.py
        └── dilatometry.py

Implementation Phases

Phase 1: Project Infrastructure (Priority: Highest)

• [ ] Set up GitHub repository infrastructure:
  • .github/workflows/
  • test-and-publish.yaml for CI/CD
  • .github/ISSUE_TEMPLATE/
  • bug.yaml
  • feature.yaml
  • docs.yaml
  • config.yaml
  • .github/
  • CODE_OF_CONDUCT.md
  • CONTRIBUTING.md
  • SECURITY.md
  • PULL_REQUEST_TEMPLATE.md
• [ ] Set up modern Python packaging:
  • pyproject.toml
  • setup.cfg
  • Move to src-layout (src/pkynetics/)
• [ ] Configure code quality tools:
  • Black for formatting
  • isort for import sorting
  • mypy for type checking
  • pytest for testing
  • Coverage.py for code coverage

Phase 2: Base Structure Implementation (Priority: High)

src/pkynetics/
├── __init__.py
├── core/
│   ├── __init__.py
│   ├── base.py      # Abstract base classes
│   └── exceptions.py
├── data_import/
│   ├── __init__.py
│   ├── base.py
│   └── implementations/
│       ├── __init__.py
│       ├── tga.py
│       ├── dsc.py
│       └── dilatometry.py
└── [other modules follow similar pattern]

Phase 3: Testing Infrastructure (Priority: High)

• [ ] Reorganize test structure:

  tests/
  ├── conftest.py
  ├── unit/
  │   ├── core/
  │   ├── data_import/
  │   └── [other modules]
  └── integration/

• [ ] Set up GitHub Actions:
  • Multiple Python versions (3.9, 3.10, 3.11)
  • Code quality checks
  • Test coverage reporting
  • Automated PyPI publishing

Phase 4: Documentation and Examples (Priority: Medium)

• [ ] Set up Read the Docs integration
• [ ] Create comprehensive API documentation
• [ ] Write migration guide
• [ ] Update examples and tutorials
• [ ] Create contributing guidelines

Phase 5: Quality Assurance (Priority: Medium)

• [ ] Implement type hints throughout codebase
• [ ] Add property-based testing
• [ ] Set up automated benchmarking
• [ ] Create performance tests

Compatibility Strategy

Version 1.0.0

• Breaking changes allowed
• Clear migration guide
• Deprecation warnings for major changes

Automated Processes

• Version bumping
• Changelog generation
• PyPI publishing
• Documentation building

Release Schedule

1. v0.9.0: Infrastructure and base structure
2. v0.9.1-v0.9.9: Incremental improvements
3. v1.0.0-rc1: Release candidate
4. v1.0.0: Stable release

Quality Metrics

• Minimum 90% test coverage
• Zero mypy errors
• All code formatted with Black
• Imports sorted with isort
• Comprehensive documentation

CI/CD Pipeline

Pipeline Stages:
1. Code Quality
   - Black formatting
   - isort check
   - mypy type checking
2. Testing
   - Unit tests
   - Integration tests
   - Coverage report
3. Documentation
   - Build docs
   - Test examples
4. Publishing
   - Build package
   - Upload to PyPI

[PPeitsch]

structure.md