Metadata-Version: 2.4
Name: usf
Version: 0.1.2
Summary: A lightweight Universal Schedule Format (USF) parser and generator.
Project-URL: Homepage, https://github.com/USF-org
Project-URL: Repository, https://github.com/USF-org/USF-Python
Project-URL: Issues, https://github.com/USF-org/USF-Python/issues
Author-email: USF-org <USF-org@outlook.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.6
Requires-Dist: jsonschema
Description-Content-Type: text/markdown

# USF-Python
USF Access Framework for Python

## Introduction
USF-Python is a Python library that provides access to the USF format for efficiency and universality.

## Features
- **Lightweight & Compact**: Optimized for efficient storage and fast parsing.
- **Supports Course Schedules**: Store course names, instructors, locations, time slots, and week rules.
- **Flexible Week Rules**: Supports "all", "even", and "odd" week patterns.
- **Simple API**: Easy to read, write, and manipulate USF files.
- **Cross-Platform**: Works on all platforms supporting Python.

## Installation
You can simply install the package with **pip**
```sh
pip install usf
```
or install it locally
```sh
python setup.py install
```

## Usage

### Reading a USF file
```python
import usf

data = usf.read("schedule.usf")
if usf.is_valid(data):
    print("Valid USF file")
    subjects = usf.get_subjects(data)
    print(subjects)
else:
    print("Invalid USF file")
```

### Creating a USF file
```python
schedule = usf.create()

definition = {
    "name": "Mathematics",
    "teacher": "Dr. Smith",
    "location": "Room 101",
    "time": [(1, 2)],  # Periods
    "week": "all"  # Every week
}
usf.add_subject(schedule, definition)
usf.save(schedule, "my_schedule.usf")
```

### Adding a Course to an Existing USF File
```python
data = usf.read("schedule.usf")
usf.add_subject(data, {
    "name": "Physics",
    "teacher": "Prof. Johnson",
    "location": "Room 203",
    "time": [(3, 4)],
    "week": "odd"
})
usf.save(data, "updated_schedule.usf")
```

### Generating a USF File from Scratch
```python
schedule = usf.create()
usf.add_subject(schedule, {
    "name": "Computer Science",
    "teacher": "Ms. Lee",
    "location": "Lab 2",
    "time": [(5, 6)],
    "week": "even"
})
usf.save(schedule, "new_schedule.usf")
```

## USF Format Specification
USF data is structured as a compact array:
- **name**: Course name (string)
- **teacher**: Instructor name (string)
- **location**: Classroom or venue (string)
- **time**: List of tuples representing periods, e.g., `[(1, 2)]` means periods 1 and 2
- **week**: `"all"`, `"even"`, or `"odd"`

Example JSON representation:
```json
{
    "subjects": [
        {
            "name": "Mathematics",
            "teacher": "Dr. Smith",
            "location": "Room 101",
            "time": [[1, 2]],
            "week": "all"
        }
    ]
}
```

## Contributing
Contributions are welcome! Feel free to open issues or submit pull requests on GitHub.

## License
This project is licensed under the MIT License.

