Skip to content

Commit 3167def

Browse files
FengzihangCodeFengzihangCode
committed
2 parents 93717d2 + 8151870 commit 3167def

File tree

2 files changed

+174
-32
lines changed

2 files changed

+174
-32
lines changed

‎README.md

Lines changed: 49 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# USF-Python
2+
Language: English｜<a href="./README_zh.md">简体中文</a>
3+
24
USF Access Framework for Python
35

6+
[![Upload Python Package](https://github.com/USF-org/USF-Python/actions/workflows/python-publish.yml/badge.svg)](https://github.com/USF-org/USF-Python/actions/workflows/python-publish.yml)
7+
8+
When the newest release only contains description updates, upload to PyPI will be failed.
9+
410
## Introduction
511
USF-Python is a Python library that provides access to the USF format for efficiency and universality.
612

@@ -22,56 +28,55 @@ python setup.py install
2228
```
2329

2430
## Usage
25-
26-
### Reading a USF file
2731
```python
2832
import usf
2933

34+
# Reading a USF file
3035
data = usf.read("schedule.usf")
3136
if usf.is_valid(data):
3237
print("Valid USF file")
3338
subjects = usf.get_subjects(data)
3439
print(subjects)
3540
else:
3641
print("Invalid USF file")
37-
```
3842

39-
### Creating a USF file
40-
```python
41-
schedule = usf.create()
43+
# Creating a USF file
44+
# Initialize the USF Generator (version 1 by default)
45+
usf_generator = usf.USFGenerator()
4246

43-
definition = {
44-
"name": "Mathematics",
45-
"teacher": "Dr. Smith",
46-
"location": "Room 101",
47-
"time": [(1, 2)], # Periods
48-
"week": "all" # Every week
49-
}
50-
usf.add_subject(schedule, definition)
51-
usf.save(schedule, "my_schedule.usf")
52-
```
47+
# Add subjects
48+
usf_generator.add_subject("Mathematics", simplified_name="Math", teacher="Dr. Smith", room="Room 101")
49+
usf_generator.add_subject("Physics", simplified_name="Phys", teacher="Prof. Johnson", room="Room 203")
5350

54-
### Adding a Course to an Existing USF File
55-
```python
51+
# Add class periods
52+
usf_generator.add_period("08:00:00", "09:30:00")
53+
usf_generator.add_period("10:00:00", "11:30:00")
54+
55+
# Add schedule entries
56+
usf_generator.add_schedule(day=1, week_type="all", subject="Mathematics", period_index=1) # Monday
57+
usf_generator.add_schedule(day=2, week_type="odd", subject="Physics", period_index=2) # Tuesday (Odd Week)
58+
59+
# Generate the USF data and save it to a file
60+
usf_generator.save_to_file("schedule.usf")
61+
62+
# Adding a Course to an Existing USF File
5663
data = usf.read("schedule.usf")
5764
usf.add_subject(data, {
5865
"name": "Physics",
5966
"teacher": "Prof. Johnson",
6067
"location": "Room 203",
61-
"time": [(3, 4)],
68+
"time": [3, 4],
6269
"week": "odd"
6370
})
6471
usf.save(data, "updated_schedule.usf")
65-
```
6672

67-
### Generating a USF File from Scratch
68-
```python
73+
# Generating a USF File from Scratch
6974
schedule = usf.create()
7075
usf.add_subject(schedule, {
7176
"name": "Computer Science",
7277
"teacher": "Ms. Lee",
7378
"location": "Lab 2",
74-
"time": [(5, 6)],
79+
"time": [5, 6],
7580
"week": "even"
7681
})
7782
usf.save(schedule, "new_schedule.usf")
@@ -88,15 +93,27 @@ USF data is structured as a compact array:
8893
Example JSON representation:
8994
```json
9095
{
91-
"subjects": [
92-
{
93-
"name": "Mathematics",
94-
"teacher": "Dr. Smith",
95-
"location": "Room 101",
96-
"time": [[1, 2]],
97-
"week": "all"
98-
}
99-
]
96+
"version": 1,
97+
"subjects": {
98+
"Mathematics": {
99+
"simplified_name": "Math",
100+
"teacher": "Dr. Smith",
101+
"room": "Room 101"
102+
},
103+
"Physics": {
104+
"simplified_name": "Phys",
105+
"teacher": "Prof. Johnson",
106+
"room": "Room 203"
107+
}
108+
},
109+
"periods": [
110+
["08:00:00", "09:30:00"],
111+
["10:00:00", "11:30:00"]
112+
],
113+
"timetable": [
114+
[1, "all", "Mathematics", 1],
115+
[2, "odd", "Physics", 2]
116+
]
100117
}
101118
```
102119

‎README_zh.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# USF-Python
2+
语言：<a href="./README.md">English</a>｜简体中文
3+
4+
适用于 Python 的 USF 访问框架
5+
6+
[![Upload Python Package](https://github.com/USF-org/USF-Python/actions/workflows/python-publish.yml/badge.svg)](https://github.com/USF-org/USF-Python/actions/workflows/python-publish.yml)
7+
8+
当最新的 Release 仅包含文档更新时，提交到 PyPI 会失败
9+
10+
## 介绍
11+
USF-Python 是为效率与通用性而生的 Python 访问框架
12+
13+
## 功能
14+
- **轻量紧凑**: 专为高效存储和快速解析进行了优化
15+
- **支持课程表**: 存储课程名称、教师、场地、时间段和周规则
16+
- **弹性周支持**: 支持“每周”、“奇数周”和“偶数周”周规则
17+
- **简单的 API**: 易于阅读、写入和操作
18+
- **跨平台**: 适用于所有支持 Python 的平台
19+
20+
## 安装
21+
你可以通过 **pip** 安装
22+
```
23+
pip install usf
24+
```
25+
或在本地通过如下命令安装
26+
```
27+
python setup.py install
28+
```
29+
30+
## 使用示例
31+
```python
32+
import usf
33+
34+
# Reading a USF file
35+
data = usf.read("schedule.usf")
36+
if usf.is_valid(data):
37+
print("Valid USF file")
38+
subjects = usf.get_subjects(data)
39+
print(subjects)
40+
else:
41+
print("Invalid USF file")
42+
43+
# Creating a USF file
44+
# Initialize the USF Generator (version 1 by default)
45+
usf_generator = usf.USFGenerator()
46+
47+
# Add subjects
48+
usf_generator.add_subject("Mathematics", simplified_name="Math", teacher="Dr. Smith", room="Room 101")
49+
usf_generator.add_subject("Physics", simplified_name="Phys", teacher="Prof. Johnson", room="Room 203")
50+
51+
# Add class periods
52+
usf_generator.add_period("08:00:00", "09:30:00")
53+
usf_generator.add_period("10:00:00", "11:30:00")
54+
55+
# Add schedule entries
56+
usf_generator.add_schedule(day=1, week_type="all", subject="Mathematics", period_index=1) # Monday
57+
usf_generator.add_schedule(day=2, week_type="odd", subject="Physics", period_index=2) # Tuesday (Odd Week)
58+
59+
# Generate the USF data and save it to a file
60+
usf_generator.save_to_file("schedule.usf")
61+
62+
# Adding a Course to an Existing USF File
63+
data = usf.read("schedule.usf")
64+
usf.add_subject(data, {
65+
"name": "Physics",
66+
"teacher": "Prof. Johnson",
67+
"location": "Room 203",
68+
"time": [3, 4],
69+
"week": "odd"
70+
})
71+
usf.save(data, "updated_schedule.usf")
72+
73+
# Generating a USF File from Scratch
74+
schedule = usf.create()
75+
usf.add_subject(schedule, {
76+
"name": "Computer Science",
77+
"teacher": "Ms. Lee",
78+
"location": "Lab 2",
79+
"time": [5, 6],
80+
"week": "even"
81+
})
82+
usf.save(schedule, "new_schedule.usf")
83+
```
84+
85+
## USF 格式规范
86+
USF 数据结构为一个紧凑的数组：
87+
- **name**: 课程名称 (string)
88+
- **teacher**: 教师姓名 (string)
89+
- **location**: 教室或场地 (string)
90+
- **time**: 时间段
91+
- **week**: `"所有周"`, `"奇数周"`, or `"偶数周"`
92+
93+
JSON 示例：
94+
```json
95+
{
96+
"version": 1,
97+
"subjects": {
98+
"Mathematics": {
99+
"simplified_name": "Math",
100+
"teacher": "Dr. Smith",
101+
"room": "Room 101"
102+
},
103+
"Physics": {
104+
"simplified_name": "Phys",
105+
"teacher": "Prof. Johnson",
106+
"room": "Room 203"
107+
}
108+
},
109+
"periods": [
110+
["08:00:00", "09:30:00"],
111+
["10:00:00", "11:30:00"]
112+
],
113+
"timetable": [
114+
[1, "all", "Mathematics", 1],
115+
[2, "odd", "Physics", 2]
116+
]
117+
}
118+
```
119+
120+
## 贡献
121+
欢迎贡献！请随时在GitHub上打开议题或提交PR
122+
123+
## 许可证
124+
该项目根据 MIT 许可证授权
125+

0 commit comments

Comments
 (0)