merge upstream

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+# Hello and thanks for using ytmusicapi! Please fill out the issue template below. Issues not following this template will be closed without comment. If you have a question only, please use GitHub discussions or gitter (linked in README).
+~~~~~~~~~~~~~
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Additional context**
+Add any other context about the problem here, such as a code sample.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+# Hello and thanks for using ytmusicapi! Please fill out the issue template below. Issues not following this template will be closed without comment. If you have a question only, please use GitHub discussions or gitter (linked in README).
+~~~~~~~~~~~~~
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/coverage.yml

@@ -3,7 +3,10 @@ name: Code coverage
 on:
   push:
     branches:
-    - master
+      - master
+  pull_request:
+    branches:
+      - master
 
 jobs:
   build:
@@ -13,23 +16,30 @@ jobs:
     - name: Setup Python
       uses: actions/setup-python@master
       with:
-        python-version: 3.7
+        python-version: 3.x
+    - name: Setup PDM
+      uses: pdm-project/setup-pdm@v3
+    - name: create-json
+      uses: jsdaniell/[email protected]
+      with:
+        name: "oauth.json"
+        dir: "tests/"
+        json: ${{ secrets.OAUTH_JSON }}
+    - name: Install dependencies
+      run: pdm install
     - name: Generate coverage report
       env:
         HEADERS_AUTH: ${{ secrets.HEADERS_AUTH }}
         TEST_CFG: ${{ secrets.TEST_CFG }}
       run: |
-        pip install -e .
-        pip install coverage
-        cd tests
-        curl -o test.mp3 https://www.kozco.com/tech/piano2-CoolEdit.mp3
-        cat <<< "$HEADERS_AUTH" > headers_auth.json
-        cat <<< "$TEST_CFG" > test.cfg
-        coverage run --source=../ytmusicapi -m unittest test.py
-        coverage xml
+        curl -o tests/test.mp3 https://www.kozco.com/tech/piano2-CoolEdit.mp3
+        cat <<< "$HEADERS_AUTH" > tests/browser.json
+        cat <<< "$TEST_CFG" > tests/test.cfg
+        pdm run pytest
+        pdm run coverage xml
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v1
+      uses: codecov/codecov-action@v3
       with:
-        file: tests/coverage.xml
+        file: coverage.xml
         flags: unittests
         fail_ci_if_error: true

.github/workflows/docsbuild.yml

@@ -1,23 +1,21 @@
 name: Build Documentation
 
 on:
-  push:
-    branches:
-    - master
+  push
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v3
       with:
         python-version: '3.x'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install ytmusicapi sphinx sphinx-rtd-theme
+        pip install . sphinx sphinx-rtd-theme
     - name: Build documentation
       run: |
         cd docs

.github/workflows/lint.yml

@@ -0,0 +1,25 @@
+name: lint
+
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: chartboost/ruff-action@v1
+      - uses: chartboost/ruff-action@v1
+        with:
+          args: format --check
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+        with:
+          python-version: "3.11"
+      - run: pip install mypy==1.8.0
+      - run:  mypy --install-types --non-interactive

.github/workflows/pythonpublish.yml

@@ -2,25 +2,28 @@ name: Upload Python Package
 
 on:
   release:
-    types: [created]
+    types: [published]
+
+permissions:
+  id-token: write # trusted publishing
+  contents: read
 
 jobs:
   deploy:
+
     runs-on: ubuntu-latest
+
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools wheel twine
-    - name: Build
-      run: |
-        python setup.py sdist bdist_wheel
-    - name: Publish distribution 📦 to PyPI
-      uses: pypa/gh-action-pypi-publish@master
-      with:
-        password: ${{ secrets.PYPI_PASSWORD }}
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '3.x'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish a Python distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,10 +1,16 @@
 .idea
 .vscode
-headers_auth.json
+**.json
 docs/build
 **.cfg
 **.mp3
 .coverage
 **/__pycache__/
 venv*/
-*.egg-info/
+*.egg-info/
+build
+dist
+.pdm-python
+.venv
+*.log
+*.xml

.pre-commit-config.yaml

@@ -1,9 +1,13 @@
 repos:
--   repo: https://github.com/pre-commit/mirrors-yapf
-    rev: v0.30.0
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.1.9
+  hooks:
+    # Run the linter.
+    - id: ruff
+    # Run the formatter.
+    - id: ruff-format
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
     hooks:
-    - id: yapf
--   repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.0
-    hooks:
-    - id: flake8
+    -   id: mypy

.readthedocs.yml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: docs/source/requirements.txt
+    - method: pip
+      path: .
+
+sphinx:
+  configuration: docs/source/conf.py
+
+formats: all

CONTRIBUTING.rst

@@ -17,7 +17,9 @@ Before making changes to the code, install the development requirements using
 
 .. code-block::
 
-    pip install -e .[dev]
+    pip install pipx
+    pipx install pdm pre-commit
+    pdm install
 
 Before committing, stage your files and run style and linter checks:
 

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 sigma67
+Copyright (c) 2024 sigma67
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -29,14 +29,15 @@ It emulates YouTube Music web client requests using the user's cookie data for a
 
 Features
 --------
+
 | **Browsing**:
 
-* search (including all filters)
+* search (including all filters) and suggestions
 * get artist information and releases (songs, videos, albums, singles, related artists)
 * get user information (videos, playlists)
 * get albums
 * get song metadata
-* get watch playlists (playlist that appears when you press play in YouTube Music)
+* get watch playlists (next songs when you press play/radio/shuffle in YouTube Music)
 * get song lyrics
 
 | **Exploring music**:
@@ -48,17 +49,29 @@ Features
 
 * get library contents: playlists, songs, artists, albums and subscriptions
 * add/remove library content: rate songs, albums and playlists, subscribe/unsubscribe artists
+* get and modify play history
 
 | **Playlists**:
 
 * create and delete playlists
 * modify playlists: edit metadata, add/move/remove tracks
 * get playlist contents
+* get playlist suggestions
 
 | **Uploads**:
 
-* Upload songs and remove them again
-* List uploaded songs, artists and albums
+* upload songs and remove them again
+* list uploaded songs, artists and albums
+
+| **Localization**:
+
+* all regions are supported (see `locations FAQ <https://ytmusicapi.readthedocs.io/en/stable/faq.html#which-values-can-i-use-for-locations>`__
+* 16 languages are supported (see `languages FAQ <https://ytmusicapi.readthedocs.io/en/stable/faq.html#which-values-can-i-use-for-languages>`__
+
+
+If you find something missing or broken,
+check the `FAQ <https://ytmusicapi.readthedocs.io/en/stable/faq.html>`__ or
+feel free to create an `issue <https://github.com/sigma67/ytmusicapi/issues/new/choose>`__.
 
 
 Usage
@@ -67,10 +80,10 @@ Usage
 
     from ytmusicapi import YTMusic
 
-    ytmusic = YTMusic('headers_auth.json')
-    playlistId = ytmusic.create_playlist('test', 'test description')
-    search_results = ytmusic.search('Oasis Wonderwall')
-    ytmusic.add_playlist_items(playlistId, [search_results[0]['videoId']])
+    yt = YTMusic('oauth.json')
+    playlistId = yt.create_playlist('test', 'test description')
+    search_results = yt.search('Oasis Wonderwall')
+    yt.add_playlist_items(playlistId, [search_results[0]['videoId']])
 
 The `tests <https://github.com/sigma67/ytmusicapi/blob/master/tests/test.py>`_ are also a great source of usage examples.
 
@@ -79,7 +92,7 @@ The `tests <https://github.com/sigma67/ytmusicapi/blob/master/tests/test.py>`_ a
 Requirements
 ==============
 
-- Python 3.5 or higher - https://www.python.org
+- Python 3.8 or higher - https://www.python.org
 
 Setup and Usage
 ===============