Metadata-Version: 2.1
Name: flexible-datetime
Version: 1.0.0
Summary: Flexible datetime handling for Python
Author: leeparnell
Author-email: 152523161+leeparnell@users.noreply.github.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: arrow (>=1.3.0,<2.0.0)
Requires-Dist: pydantic (>=2.7.4,<3.0.0)
Description-Content-Type: text/markdown


# Flexible Datetime

A Python library providing flexible datetime creation and handling with masked comparison capabilities, built on Arrow and Pydantic.

## Features

Parse dates and times from:
- ISO format strings
- Partial dates ("2023-06", "2023")
- Natural language ("June 15th, 2023", "next thursday")
- Component dictionaries ({"year": 2023, "month": 6})
- Python datetime/date objects
- Arrow objects
- Component masking for selective comparisons
- Multiple serialization formats

## Installation

```bash
pip install flexible-datetime
```

## Usage

```python

from flexible_datetime import flextime

# Parse various formats
ft = flextime("2023-06")                      # Partial date
ft = flextime({"year": 2023, "month": 6})     # From components
ft = flextime("next thursday at 2pm")         # Natural language
ft = flextime("2023-06-15T14:30:45")          # ISO format

print(ft) 
# Output: 2023-06-15T14:30:45
```

### Output Formats

```python
ft = flextime("2023-06-15")          # ISO format

# Choose output formats
print(ft) # default: Serialize as shortest possible datetime format.                      
# Output: 2023-06-15
print(ft.to_str("flex")) # JSON with mask           
# Output: {'dt': '2023-06-15T00:00:00+00:00', 'mask': '0001111'}

print(ft.to_str("datetime")) # Full ISO format
# Output: 2023-06-15T00:00:00+00:00
print(ft.to_str("components")) # Component dict
# Output {'year': 2023, 'month': 6, 'day': 15}
```


### Component Masking

Mask specific components for flexible comparisons:

```python
# Mask specific components
ft = flextime("2023-06-15T14:30")
ft.apply_mask(hour=True, minute=True)  # Mask time components
print(ft)                              # "2023-06-15"

# Clear all masks
ft.clear_mask()

# Use only specific components
ft.use_only("year", "month")           # Only use year and month
print(ft)                              # "2023-06"

# Use masking for flexible comparisons
ft1 = flextime("2023-01-15")
ft2 = flextime("2024-01-15")
ft1.apply_mask(year=True) # Mask the year
ft2.apply_mask(year=True) # Mask the year
print(ft1 == ft2) # True - years are masked
```

### Component Access

Access individual components directly:

```python
ft = flextime("2023-06-15T14:30")
print(ft.year)                          # 2023
print(ft.month)                         # 6
print(ft.day)                           # 15
print(ft.hour)                          # 14
print(ft.minute)                        # 30
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

