Merge pull request #13 from notjagan/performance-calculation

Add performance calculation support and documentation

.github/workflows/build.yml

@@ -42,7 +42,7 @@ jobs:
           dotnet-version: '6.0.x'
 
       - name: Build wheels
-        uses: pypa/[email protected].2
+        uses: pypa/[email protected].5
         env:
           CIBW_BUILD: ${{ matrix.pyver }}-*
           CIBW_ARCHS: ${{ matrix.platform.arch }}

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "vibrio/vendor/vibrio"]
 	path = vibrio/vendor/vibrio
-	url = git@github.com:notjagan/vibrio.git
+	url = https://github.com/notjagan/vibrio.git

.readthedocs.yaml

@@ -0,0 +1,21 @@
+version: 2
+
+submodules:
+  include: all
+  recursive: true
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  apt_packages:
+    - dotnet-sdk-6.0
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+   install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt

README.md

@@ -1,2 +1,21 @@
-# vibrio-python
-python bindings for https://github.com/notjagan/vibrio
+# vibrio-python ([documentation](https://vibrio-python.readthedocs.io/en/latest/))
+
+[![PyPI](https://img.shields.io/pypi/v/vibrio.svg)](https://pypi.org/project/vibrio/)
+[![Build](https://github.com/notjagan/vibrio-python/actions/workflows/build.yml/badge.svg)](https://github.com/notjagan/vibrio-python/actions/workflows/build.yml)
+[![CodeFactor](https://www.codefactor.io/repository/github/notjagan/vibrio-python/badge)](https://www.codefactor.io/repository/github/notjagan/vibrio-python)
+
+Python library for interfacing with osu!lazer functionality. Acts as bindings for https://github.com/notjagan/vibrio under the hood.
+
+# Installation
+
+`pip install vibrio`
+
+Supports Python 3.9+.
+
+Tested (through `cibuildwheel` deployment) and published on `pip` on the following platforms:
+- Ubuntu (via manylinux and musl) (x86)
+- macOS (x86, arm64)
+    - arm is currently untested due to unavailability through GitHub actions hosting
+- Windows (x86 and AMD64)
+
+If you do not have one of the supported platforms (or otherwise want to build from source), simply clone the repository and use the `build` subcommand (and/or any superset of `build` like `sdist`) in `setup.py` to produce an installable package, then use `pip install` on the result. This will require having the `dotnet` C# SDK on the system path to compile the server solution.

docs/.gitignore

@@ -0,0 +1,41 @@
+# sphinx build folder
+_build
+
+# Compiled source #
+###################
+*.com
+*.class
+*.dll
+*.exe
+*.o
+*.so
+
+# Packages #
+############
+# it's better to unpack these files and commit the raw source
+# git has its own built in compression methods
+*.7z
+*.dmg
+*.gz
+*.iso
+*.jar
+*.rar
+*.tar
+*.zip
+
+# Logs and databases #
+######################
+*.log
+*.sql
+*.sqlite
+
+# OS generated files #
+######################
+.DS_Store?
+ehthumbs.db
+Icon?
+Thumbs.db
+
+# Editor backup files #
+#######################
+*~

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,21 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+project = "vibrio"
+copyright = "2024, notjagan"
+author = "notjagan"
+
+extensions = ["sphinx.ext.autodoc", "numpydoc"]
+
+numpydoc_class_members_toctree = False
+numpydoc_show_inherited_class_members = False
+autodoc_default_options = {"members": True, "undoc-members": True}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+html_sidebars = {"**": ["localtoc.html"]}

docs/index.rst

@@ -0,0 +1,39 @@
+Welcome to vibrio's documentation!
+==================================
+All normal use-cases should be available through a top-level import
+(`from vibrio import ...`); see :mod:`vibrio`. Internal documentation is
+provided at :mod:`vibrio.lazer` and :mod:`vibrio.types`, although use of these modules
+should not be necessary.
+
+Quickstart
+----------
+>>> from vibrio import HitStatistics, Lazer, OsuMod
+>>> with Lazer() as lazer:
+...     attributes = lazer.calculate_performance(
+...         beatmap_id=1001682,
+...         mods=[OsuMod.HIDDEN, OsuMod.DOUBLE_TIME],
+...         hitstats=HitStatistics(
+...             count_300=2019, count_100=104, count_50=0, count_miss=3, combo=3141
+...         ),
+...     )
+...     attributes.total
+1304.35
+
+See :class:`vibrio.Lazer` (or :class:`vibrio.LazerAsync` for the asynchronous
+implementation) for more details.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   vibrio
+   vibrio.lazer
+   vibrio.types
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.in

@@ -0,0 +1,3 @@
+sphinx==7.2.6
+numpydoc==1.6.0
+pydata-sphinx-theme==0.15.2

docs/requirements.txt

@@ -0,0 +1,78 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+#    pip-compile '.\requirements.in'
+#
+accessible-pygments==0.0.4
+    # via pydata-sphinx-theme
+alabaster==0.7.16
+    # via sphinx
+babel==2.14.0
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.12.3
+    # via pydata-sphinx-theme
+certifi==2024.2.2
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+colorama==0.4.6
+    # via sphinx
+docutils==0.20.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+idna==3.6
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.3
+    # via
+    #   numpydoc
+    #   sphinx
+markupsafe==2.1.5
+    # via jinja2
+numpydoc==1.6.0
+    # via -r .\requirements.in
+packaging==23.2
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+pydata-sphinx-theme==0.15.2
+    # via -r .\requirements.in
+pygments==2.17.2
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
+requests==2.31.0
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.5
+    # via beautifulsoup4
+sphinx==7.2.6
+    # via
+    #   -r .\requirements.in
+    #   numpydoc
+    #   pydata-sphinx-theme
+sphinxcontrib-applehelp==1.0.8
+    # via sphinx
+sphinxcontrib-devhelp==1.0.6
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.5
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.7
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.10
+    # via sphinx
+tabulate==0.9.0
+    # via numpydoc
+typing-extensions==4.9.0
+    # via pydata-sphinx-theme
+urllib3==2.2.1
+    # via requests

docs/vibrio.lazer.rst

@@ -0,0 +1,4 @@
+vibrio.lazer
+============
+.. automodule:: vibrio.lazer
+    :members:

docs/vibrio.rst

@@ -0,0 +1,4 @@
+vibrio
+======
+.. automodule:: vibrio
+    :members:

docs/vibrio.types.rst

@@ -0,0 +1,4 @@
+vibrio.types
+============
+.. automodule:: vibrio.types
+    :members:

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vibrio"
-version = "0.2.0"
+version = "0.3.0"
 readme = "README.md"
 requires-python = ">=3.9"
 license = { file = "LICENSE" }

setup.py

@@ -67,18 +67,18 @@ def finalize_options(self) -> None:
 
     def run(self) -> None:
         def onerror(
-            func: Callable[..., Any], path: str, ex_info: tuple[Exception, ...]
+            func: Callable[[str], Any], path: str, ex_info: tuple[BaseException, ...]
         ) -> None:
-            ex, *_ = ex_info
+            ex_type, *_ = ex_info
             # resolve any permission issues
-            if ex is PermissionError and not os.access(path, os.W_OK):
-                os.chmod(path, stat.S_IWUSR)
+            if ex_type is PermissionError and not os.access(path, os.W_OK):
+                os.chmod(path, os.stat(path).st_mode | stat.S_IWUSR)
                 func(path)
             # ignore missing file
-            elif ex is FileNotFoundError:
+            elif ex_type is FileNotFoundError:
                 pass
             else:
-                raise
+                raise ex_type
 
         shutil.rmtree(EXTENSION_DIR, onerror=onerror)
         EXTENSION_DIR.mkdir(parents=True, exist_ok=True)
@@ -101,13 +101,15 @@ def onerror(
         publish_dir = server_dir / "publish"
         for path in publish_dir.glob("*.zip"):
             with ZipFile(path, "r") as zip_file:
-                zip_file.extractall(EXTENSION_DIR)
+                for filename in zip_file.filelist:
+                    executable = Path(zip_file.extract(filename, EXTENSION_DIR))
+                    executable.chmod(executable.stat().st_mode | stat.S_IEXEC)
 
 
 class CustomBuild(build):
     """Build process including compiling server executable."""
 
-    sub_commands = [("build_vendor", None)] + build.sub_commands
+    sub_commands = [("build_vendor", None)] + build.sub_commands  # type: ignore
 
 
 setup(

vibrio/__init__.py

@@ -1,2 +1,20 @@
-from vibrio.lazer import Lazer as Lazer
-from vibrio.lazer import LazerAsync as LazerAsync
+"""
+Top-level imports and types; see :class:`Lazer` and :class:`LazerAsync`.
+"""
+
+from vibrio.lazer import Lazer, LazerAsync
+from vibrio.types import (
+    HitStatistics,
+    OsuDifficultyAttributes,
+    OsuMod,
+    OsuPerformanceAttributes,
+)
+
+__all__ = [
+    "Lazer",
+    "LazerAsync",
+    "HitStatistics",
+    "OsuMod",
+    "OsuPerformanceAttributes",
+    "OsuDifficultyAttributes",
+]