From 35f9a69ba7f6cf1ffe8b7810b0533b3e2852cc5d Mon Sep 17 00:00:00 2001 From: Kutu Date: Sun, 2 Jun 2024 02:29:24 +0200 Subject: [PATCH] Add getting stared guide and publish to PyPI workflow --- .github/workflows/publish.yml | 27 ++++++++++++++++++++++ README.md | 43 ++++++++++++++++++++++++++++++++--- TODO.md | 3 ++- justfile | 1 + mkdocs.yml | 39 ++++++++++++++++++++++++++++++- pyproject.toml | 1 - scripts/pre-commit.sh | 0 src/knuckles/_api.py | 4 +++- 8 files changed, 111 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/publish.yml mode change 100755 => 100644 scripts/pre-commit.sh diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..384edbb --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,27 @@ +name: Publish update to PyPI + +on: + - workflow_dispatch + - release: + types: publised + +jobs: + publish-pypi: + runs-on: ubuntu-latest + + environment: release + permissions: + id-token: write + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11.0" + + + - run: python3 -m pip install build + - run: python3 -m build --sdist --wheel --outdir dist/ . + + - name: Publish updated package to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/README.md b/README.md index 4557417..fb02024 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,47 @@ ## Compatiblity Knuckles **only** works with servers compatible with the REST API version 1.4.0 onwards (Subsonic 4.2+). -It follows strictly the [OpenSubsonic API Spec](https://opensubsonic.netlify.app/docs/opensubsonic-api/), it being fully retro-compatible with the original [Subsonic API](https://subsonic.org/pages/api.jsp). +It follows strictly the [OpenSubsonic API Spec](https://opensubsonic.netlify.app/docs/opensubsonic-api/), being fully retro-compatible with the original [Subsonic API](https://subsonic.org/pages/api.jsp). -### Quickstart -... +## Getting Started + +### Make It Available +First install the package: + +```sh title="Command line" +python3 -m pip install knuckles +``` + +Or add it to your project: + +```toml title="pyproject.toml" +project = [ + "knuckles>=1.0.0" +] +``` + +### Using It + +```python3 title="__main__.py" +import knuckles + +server = knuckles.subsonic( + # Adding https:// is done automatically, + # /rest should never be added to the URL + url = "example.com", + user = "kutu", + password = "caisopea", + client = "knuckles client" +) + +ping = server.ping() + +# Print the supported version of the OpenSubsonic REST API +print(ping.version) +``` + +### Learning More +To start making more complex interactions with the API make use of [the reference](https://kutu-dev.github.io/knuckles/reference/Api/). Enjoy coding and good luck! ## Acknowledgements Created with :heart: by [Jorge "Kutu" Dobón Blanco](https://dobon.dev). diff --git a/TODO.md b/TODO.md index 4d77ef8..40a6d0e 100644 --- a/TODO.md +++ b/TODO.md @@ -2,4 +2,5 @@ - [ ] Document in contributing why attributes are double typed. - [ ] Add general documentation and tutorials. -- [ ] Fix PR requirements. +- [ ] Explain why CI uses `24.04` and not latest. +- [ ] Write that compat funcions for non standard behaviour servers is not planed. diff --git a/justfile b/justfile index 3a2e9d9..9ba0f17 100644 --- a/justfile +++ b/justfile @@ -39,6 +39,7 @@ check: # Install a pre-commit hook to ensure that the CI will pass install-hook: uninstall-hook cp scripts/pre-commit.sh .git/hooks/pre-commit + chmod +x .git/hooks/pre-commit # Uninstall the pre-commit hook uninstall-hook: diff --git a/mkdocs.yml b/mkdocs.yml index ce13675..5e577d8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,11 +5,41 @@ repo_name: kutu-dev/knuckles theme: name: material + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + primary: red + accent: red + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: red + accent: red + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: red + accent: red + toggle: + icon: material/brightness-4 + name: Switch to system preference + features: - navigation.tabs + - content.code.copy nav: - - Home: "index.md" + - Home: + Home: "index.md" + Contributing: "contributing.md" - Reference: "reference/" plugins: @@ -29,5 +59,12 @@ plugins: merge_init_into_class: true markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences - pymdownx.snippets - pymdownx.emoji diff --git a/pyproject.toml b/pyproject.toml index 03adb3b..eab772e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,7 +37,6 @@ docs = [ requires = ["setuptools"] build-backend = "setuptools.build_meta" - [tool.ruff.lint] select = ["E", "F", "I001"] diff --git a/scripts/pre-commit.sh b/scripts/pre-commit.sh old mode 100755 new mode 100644 diff --git a/src/knuckles/_api.py b/src/knuckles/_api.py index 77a1f52..648937a 100644 --- a/src/knuckles/_api.py +++ b/src/knuckles/_api.py @@ -119,7 +119,8 @@ def generate_url(self, endpoint: str, extra_params: dict[str, Any]) -> str: prepared_request = PreparedRequest() prepared_request.prepare_url( - f"{self.url}/rest/{endpoint}", {**self._generate_params(extra_params)} + f"{self.url}/rest/{endpoint}", {** + self._generate_params(extra_params)} ) # Ignore the type error caused by the url parameter of prepared_request @@ -141,6 +142,7 @@ def raw_request( [`requests`](https://docs.python-requests.org/en/latest/index.html) `response` object of the executed request. """ + match self.request_method: case RequestMethod.POST: return requests.post(