# Changelog

All notable changes to the KML ORM project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.1.1] - 2025-09-28

### Documentation

- **Query Method Behavior Reference** - Added documentation clarifying query method behavior
  - Created detailed truth table showing that `filter()`, `exclude()`, `get()` etc. operate on direct children only by default
  - Added clear examples demonstrating when to use `.all()` vs `.children()` vs direct query methods

## [1.1.0] - 2025-09-28

### Fixed

- **Recursive `.all()` collection from folders** - Fixed critical bug where `folder.placemarks.all()` only returned direct children instead of all nested elements
  - `.all()` now correctly returns ALL elements recursively when called from a folder
  - Example: `folder.placemarks.all()` now returns placemarks from the folder AND all nested subfolders
  - Affects all element types: placemarks, folders, paths, polygons, points, multigeometries
  - This fix makes the API work as documented and intended
  - Updated documentation examples in tutorial.rst and KML_ORM_SPECIFICATION.md to reflect correct behavior

- **Geometry collection includes all sources** - Fixed geometry managers (Points, Paths, Polygons) to collect from all sources
  - `.all()` on geometry managers now collects from:
    - Standalone geometry elements at any level
    - Geometries within Placemarks (e.g., `placemark.point`, LineStrings that become Paths)
    - Geometries within MultiGeometry containers (both standalone and in Placemarks)
  - Example: `kml.points.all()` returns ALL Points including those from root-level Placemarks
  - Example: `folder.paths.all()` returns ALL Paths including those from Placemarks with LineStrings
  - Added support for parsing standalone Point/MultiGeometry elements directly in folders
  - All geometry types (Points, Paths, Polygons) now have consistent collection behavior

- **Renamed internal method for clarity** - Renamed `_collect_folder_elements` to `_collect_nested_elements`
  - More semantically accurate name reflecting that it collects from any nested containers
  - Allows subclasses to override for custom collection behavior

### Added

- **Comprehensive test coverage for spatial calculations** - Added extensive tests for spatial calculation methods
  - Created `test_spatial_interpolation.py` with 29 tests covering interpolation and bounding box calculations
  - Created `test_spatial_distances_to_many.py` with 14 tests for bulk distance calculations
  - Improved test coverage for `kmlorm/spatial/calculations.py` from ~46% to 77%
  - Tests cover edge cases, None handling, various input types, and real-world scenarios
  - All spatial calculation methods (`interpolate`, `bounding_box`, `distances_to_many`) now thoroughly tested

## [1.0.1] - 2025-09-28

### Major Release - Production Ready

This release marks KML ORM as production-ready with a stable, intuitive API, comprehensive testing, and excellent code quality.

### Added

#### New API Methods
- **`.children()` method** - New intuitive method for accessing only direct child elements without traversing nested folders
  - Clear hierarchical semantics for better code readability
  - Consistent behavior across all manager types (placemarks, folders, paths, polygons, etc.)
  - Example: `kml.placemarks.children()` returns only root-level placemarks

#### Test Infrastructure
- **Centralized test fixtures** in `conftest.py` reducing test code duplication by ~60%
  - `nested_kml_content` - Deep folder nesting scenarios
  - `sample_placemarks` - Reusable Placemark objects
  - `stores_kml_content` - Business location testing
  - `empty_kml_content` - Edge case testing
  - `invalid_kml_content` - Error handling validation
  - Coordinate fixtures for spatial testing (NYC, London, Baltimore)
  - Known distance data for parametrized tests

#### Documentation
- Comprehensive test coverage for all documentation examples
- All code examples in docs are now validated through automated tests
- Added migration guide for API changes
- Enhanced API documentation with deprecation notices

### Changed

#### Breaking API Changes (with full backward compatibility)
- **`.all()` method behavior** - Now returns ALL elements including those in nested folders (previously required `flatten=True`)
  - Old: `kml.placemarks.all(flatten=True)` → New: `kml.placemarks.all()`
  - Old: `kml.placemarks.all()` → New: `kml.placemarks.children()`
  - Deprecation warnings guide users to new patterns
  - Full backward compatibility maintained during transition

#### Test Suite Improvements
- **Pytest standardization** - Migrated from unittest.TestCase to pure pytest patterns
  - Converted 8 test files from unittest to pytest style
  - Replaced `setUp()` with pytest fixtures
  - Changed assertions from `self.assertEqual()` to `assert ==`
  - Improved test readability and maintainability

#### Code Quality Enhancements
- **Perfect linting score** - Achieved pylint 10.00/10 (from 9.93/10)
  - Fixed all attribute-defined-outside-init warnings
  - Resolved line-too-long issues
  - Added proper lazy logging formatting
  - Fixed all unused-argument warnings

- **Complete type safety** - Zero mypy errors (from 37 errors)
  - Added comprehensive type annotations
  - Fixed all None-check operations
  - Resolved generator return type issues
  - Complete type coverage across codebase

### Deprecated

- **`flatten` parameter** in `.all()` method
  - `flatten=True` - Use `.all()` instead (new default behavior)
  - `flatten=False` - Use `.children()` instead
  - Shows clear deprecation warnings with migration guidance
  - Will be removed in version 2.0.0

### Fixed

#### Type Safety Issues
- Fixed operations on potentially None values in spatial calculations
- Added proper None checks before coordinate operations
- Fixed incompatible type errors in test batch processing
- Resolved unreachable code in Store.distance_to_customer method

#### Test Issues
- Fixed class attribute initialization in test fixtures
- Resolved pytest fixture return type annotations
- Fixed lazy logging formatting in error handlers
- Corrected test expectations for new API behavior

### Performance

- Maintained <10% performance degradation with new `.all()` behavior
- All 491 tests passing with 91% code coverage
- No memory usage regressions detected
- Optimized QuerySet operations for nested element collection

### Metrics

- **Test Suite**: 491 tests, 100% pass rate
- **Code Coverage**: 91% (maintained)
- **Pylint Score**: 10.00/10 (perfect)
- **Type Checking**: 0 errors in 58 source files
- **Documentation Tests**: All examples validated and working

### Internal Changes

- Updated all internal code to use `.children()` for direct child access
- Migrated all documentation examples to new API patterns
- Removed deprecated test compatibility layer
- Cleaned up test suite removing all `flatten` parameter usage
- Standardized on pytest fixtures for all test data

### Developer Experience

- More intuitive API following Django-like conventions
- Clearer code intent with semantic method names
- Comprehensive migration documentation
- Type-safe throughout with full mypy coverage
- Consistent test patterns using pytest best practices

### Migration Guide

#### For Users

**Before (v0.x):**
```python
# Getting all elements including nested
all_items = kml.placemarks.all(flatten=True)

# Getting only direct children
root_items = kml.placemarks.all()
```

**After (v1.0.0):**
```python
# Getting all elements including nested
all_items = kml.placemarks.all()

# Getting only direct children
root_items = kml.placemarks.children()
```


### Contributors

This release represents significant improvements to code quality, API design, and testing infrastructure, making KML ORM ready for production use.

---

[1.0.0]: https://github.com/yourusername/kml_orm/releases/tag/v1.0.0