add docs & release notes

docs/get-charts-for-one-game-mode.py

@@ -0,0 +1,13 @@
+from typing import Iterator
+from simfile.types import Chart
+
+# Imperative version
+def charts_for_stepstype(charts, stepstype="dance-single") -> Iterator[Chart]:
+    for chart in charts:
+        if chart.stepstype == stepstype:
+            yield chart
+
+
+# One-liner version
+def charts_for_stepstype(charts, stepstype="dance-single") -> Iterator[Chart]:
+    yield from filter(lambda chart: chart.stepstype == stepstype, charts)

docs/get-the-hardest-chart.py

@@ -0,0 +1,25 @@
+from typing import Optional, Sequence
+from simfile.types import Chart
+
+# Imperative version
+def get_hardest_chart(charts) -> Optional[Chart]:
+    hardest_chart: Optional[Chart] = None
+    hardest_meter: Optional[int] = None
+
+    for chart in charts:
+        # Remember to convert `meter` to an integer for comparisons
+        meter = int(chart.meter or "1")
+        if hardest_meter is None or meter > hardest_meter:
+            hardest_chart = chart
+            hardest_meter = meter
+
+    return hardest_chart
+
+
+# One-liner version
+def get_hardest_chart(charts: Sequence[Chart]) -> Optional[Chart]:
+    return max(
+        charts,
+        key=lambda chart: int(chart.meter or "1"),
+        default=None,
+    )

docs/mirror-a-charts-notes.py

@@ -0,0 +1,24 @@
+from typing import Iterator
+from simfile.types import Chart
+from simfile.notes import Note, NoteData
+
+def mirror_note(note: Note, columns: int) -> Note:
+    # Make a new Note with all fields the same except for column
+    return note._replace(
+        # You could replace this expression with anything you want
+        column=columns - note.column - 1
+    )
+
+def mirror_notes(notedata: NoteData) -> Iterator[Note]:
+    columns = notedata.columns
+    for note in notedata:
+        yield mirror_note(note, columns)
+
+def mirror_chart_in_place(chart: Chart) -> None:
+    notedata = NoteData(chart)
+    mirrored = NoteData.from_notes(
+        mirror_notes(notedata),
+        columns=notedata.columns,
+    )
+    # Assign str(NoteData) to Chart.notes to update the chart's notes
+    chart.notes = str(mirrored)

docs/remove-all-but-one-chart.py

@@ -0,0 +1,24 @@
+from typing import Optional, Sequence
+from simfile.types import Chart, Charts, Simfile
+
+# When you have multiple parameters of the same type (str in this case),
+# it's good practice to use a * pseudo-argument to require them to be named
+def find_chart(
+    charts: Sequence[Chart], *, stepstype: str, difficulty: str
+) -> Optional[Chart]:
+    for chart in charts:
+        if chart.stepstype == stepstype and chart.difficulty == difficulty:
+            return chart
+
+
+def remove_other_charts(
+    sf: Simfile, *, stepstype="dance-single", difficulty="Challenge"
+):
+    the_chart = find_chart(sf.charts, stepstype=stepstype, difficulty=difficulty)
+    if the_chart:
+        # Replace the simfile's charts with a list of one
+        sf.charts = [the_chart]  # type: ignore
+    else:
+        # You could alternatively raise an exception, pick a different chart,
+        # set sf.charts to an empty list, etc.
+        print(f"No {stepstype} {difficulty} chart found for {repr(sf)}")

releasenotes/2.1.0/example1.py

@@ -0,0 +1,7 @@
+from simfile.dir import SimfilePack
+
+pack = SimfilePack(R"C:\StepMania\Songs\My Pack")
+for simfile_dir in pack.simfile_dirs():
+    print("Simfile paths: ", simfile_dir.sm_path, simfile_dir.ssc_path)
+    sim = simfile_dir.open()
+    print("Title:", sim.title)

releasenotes/2.1.0/example2.py

@@ -0,0 +1,4 @@
+import simfile
+
+for sim, filename in simfile.openpack(R"C:\StepMania\Songs\My Pack"):
+    print(f"Loaded {sim.title} from {filename}")

releasenotes/2.1.0/example3.py

@@ -0,0 +1,6 @@
+import simfile
+from fs.zipfs import ZipFS
+
+zip_fs = ZipFS(R"C:\Users\micro\Downloads\Coconut [13].zip")
+sim, filename = simfile.opendir("Coconut", filesystem=zip_fs)
+print(f"Loaded {sim.title} from {filename} inside ZIP")

releasenotes/2.1.0/example4.py

@@ -0,0 +1,7 @@
+from simfile.dir import SimfileDirectory
+
+simfile_dir = SimfileDirectory(R"C:\StepMania\Songs\My Pack\My Song")
+assets = simfile_dir.assets()
+assert assets.music, "No music file"
+with open(assets.music, "rb") as audio_file:
+    ...