README.md (4328B)
1 # Ungana 2 3 **Ungana** is a Python CLI tool for creating customized iCalendar (`.ics`) files. 4 5 6 ## Requirements 7 - Python 3.8+ 8 - pip 20.0+ 9 10 11 ## Setup (Recommended) 12 13 ### Create a Virtual Environment 14 First, create and activate a virtual environment to isolate the project dependencies: 15 16 ```bash 17 python3 -m venv venv 18 ``` 19 20 ``` 21 source venv/bin/activate 22 ``` 23 24 ## Installation 25 26 #### Editable Mode 27 ```bash 28 cd ungana 29 pip install -e . 30 ``` 31 32 ## Without Installation 33 ```bash 34 python3 -m ungana.runnable.ungana_cal_cli 35 ``` 36 37 ## Commands 38 39 #### 1.Create 40 To create an event entry, the `create` command can be used as: 41 42 `create -s SUMMARY [--sf SUMMARY_FILE] -d DESCRIPTION [--df DESCRIPTION_FILE] --start START -l LOCATION -o ORGANIZER --tzid 43 TZID [--end END] [--duration DURATION] ` 44 45 ## Command Arguments 46 47 | Option | Required | Input Type | Description | Format Example | 48 |-----------------------------|----------|------------------|-----------------------------------------------------------------------------------------------------|--------------------------------------| 49 | `-s`, `--summary` | Yes | Freeform text | Event title (short title shown in display). | `"Team Meeting"` | 50 | `-sf`, `--summary-file` | No | File path string | File containing the event summary. | `summary.txt` | 51 | `-d`, `--description` | Yes | Freeform text | Event details (brief, concise description). | `"Quarterly review"` | 52 | `-df`, `--description-file` | No | File path string | File containing the event description. | `description.txt` | 53 | `--start` | Yes | Datetime | Start time of the event. | `"10-09-2025 14:00"` (or ISO format) | 54 | `--end` | No | Datetime | End time of the event. | `"10-09-2025 16:00"` | 55 | `--duration` | No | Duration string | Duration of the event (alternative to `--end`). | `"PT2H"` (ISO 8601) | 56 | `-l`, `--location` | Yes | Freeform string | Event venue or location. | `"Conference Room A"` | 57 | `-o`, `--organizer` | Yes | Freeform string | Organizer’s contact (e.g., name or email). | `"events@company.com"` | 58 | `--tzid` | Yes | Freeform string | Timezone identifier | `"Africa/Nairobi"` | 59 | `-f`, `--file` | No | Freeform string | Output filename for the generated iCalendar file.<br>If not provided, a safe timestamped filename (e.g., `event_20250820_083410.ics`) will be used. | `"team_meeting.ics"` | 60 61 62 #### 2.Edit 63 Using the `edit` command, you can modify an existing ical file's fields. 64 65 `edit -i ICAL_FILE_Path -s [SUMMARY] -d [DESCRIPTION] --start [START] -l [LOCATION] -o [ORGANIZER] ...` 66 67 | Option | Required | Description | Format Example | 68 |--------------------|----------|-------------------|----------------------| 69 | `-i`, `--ical` | Yes | Path to ical file | `"/events/ical.ics"` | 70 | `-a`, `--all` | No | Apply to all events in the iCal file. If omitted, only the first event is modified. | - | 71 | `-c`, `--contact` | No | Contact information | `"events@abc.org"` | 72 | `-p`, `--poster` | No | Event headline image | `"events/posters/poster.png"` | 73 | `-ld`, `--long` | No | Exhaustive description of the event | `"events/team/event_description.txt"` |