Metadata-Version: 2.4
Name: calprint
Version: 0.1.0
Summary: Print human-readable summaries of iCalendar (.ics) files.
Keywords: calendar,icalendar,ics,cli
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: icalendar>=7,<8
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/schmidma/calprint
Project-URL: Repository, https://github.com/schmidma/calprint
Project-URL: Issues, https://github.com/schmidma/calprint/issues
Project-URL: Releases, https://github.com/schmidma/calprint/releases
Description-Content-Type: text/markdown

# calprint

`calprint` is a small Python CLI that reads an iCalendar (`.ics`) file and
prints a human-readable summary of the calendar and its `VEVENT` entries.

It is intentionally simple:

- plain text output
- no recurrence expansion
- deterministic event ordering
- modern Python (`>=3.12`)
- `uv`-managed development workflow
- `ruff` formatting and linting
- `ty` type checking

Repository: <https://github.com/schmidma/calprint>

Issues: <https://github.com/schmidma/calprint/issues>

## Install

### Run once with `uvx`

```bash
uvx calprint path/to/calendar.ics
```

### Install as a tool with `uv`

```bash
uv tool install calprint
calprint path/to/calendar.ics
```

### Install with `pip`

```bash
pip install calprint
calprint path/to/calendar.ics
```

## Usage

### Console command

```bash
calprint path/to/calendar.ics
```

### Module execution

```bash
python -m calprint path/to/calendar.ics
```

### Version

```bash
calprint --version
```

## Output

`calprint` prints:

- calendar name, version, product ID, and method
- timezone identifiers declared in `VTIMEZONE`
- total `VEVENT` count
- per-event summary, start, end, UID, organizer, attendees, location, and status

Missing optional values are rendered as `-`.

Dates and datetimes are formatted as:

- dates: `YYYY-MM-DD`
- naive datetimes: `YYYY-MM-DD HH:MM`
- timezone-aware datetimes: `YYYY-MM-DD HH:MM TZ`

## Example

```bash
uv run calprint tests/fixtures/example_meeting.ics
```

Example output:

```text
Calendar
  Name: -
  Version: 2.0
  Product ID: -//Example Industries//calprint//EN
  Method: REQUEST
  Timezones: Europe/Berlin
  Events: 1

Event 1
  Summary: Quarterly Roadmap Review and Planning Session
  Start: 2026-04-14 08:30 CEST
  End: 2026-04-14 09:30 CEST
  UID: roadmap-review-20260414@example.test
  Organizer: Taylor Example
  Attendees: Alex Example, Jordan Example
  Location: Virtual Meeting Room 3
  Status: CONFIRMED
```

## Development

Create the project environment:

```bash
uv sync --dev
```

Run the CLI locally:

```bash
uv run calprint tests/fixtures/example_meeting.ics
```

Quality commands:

```bash
uv run ruff format .
uv run ruff format --check .
uv run ruff check .
uv run ty check src
uv run pytest
```

Build distributions:

```bash
uv build --no-sources
```

## Test Fixtures

The repository includes a small fixture corpus under `tests/fixtures/`.

- synthetic meeting and invalid fixtures are safe to publish
- a few fixtures are adapted from the `collective/icalendar` test suite for
  interoperability coverage

See `tests/fixtures/README.md` for provenance details.

## Releasing

### Local release steps

1. Update the package version.

```bash
uv version 0.2.0
```

2. Run the local checks.

```bash
uv run ruff format --check .
uv run ruff check .
uv run ty check src
uv run pytest
uv build --no-sources
```

3. Commit the version bump.

4. Create and push a version tag.

```bash
git tag v0.2.0
git push origin v0.2.0
```

### GitHub automation

Pushing a `v*` tag triggers the publish workflow, which will:

- validate that the tag matches `project.version`
- build the wheel and source distribution
- smoke-test both artifacts
- publish to PyPI with `uv publish`
- create a GitHub Release for the tag and attach the built artifacts

### One-time publish setup

Before the publish workflow can succeed, configure:

1. a GitHub environment named `pypi`
2. a PyPI trusted publisher pointing at this repository and workflow

## License

MIT

## AI Assistance

This project was developed with support from AI coding agents. The repository,
implementation plan, and code changes were produced collaboratively with AI-assisted
development tools.
