file handles and metadata, and convert between different audio formats.
"""
+import base64
+import datetime
+import logging
+import pathlib
+import re
+import subprocess
+from typing import Any, Union
+import urllib
+
from mutagen import id3, flac, mp3, mp4, oggflac, oggopus, oggvorbis, wave
-from . import (
- base64, datetime, logging, pathlib, re, subprocess, urllib,
- utility, FOUND_FFMPEG, FFMPEG_CODECS, Any, Union
-)
+from . import utility, FOUND_FFMPEG, FFMPEG_CODECS
from .qobuz import _parse_performers
__all__ = ["Audio", "FLACAudio", "MP3Audio", "MP4Audio", "OggAudio",
@@ -1772,7 +1781,7 @@ Source code for minim.audio
-[docs]
+[docs]
class OggAudio(Audio, _VorbisComment):
r"""
diff --git a/docs/_modules/minim/discogs.html b/docs/_modules/minim/discogs.html
new file mode 100644
index 0000000..1c53551
--- /dev/null
+++ b/docs/_modules/minim/discogs.html
@@ -0,0 +1,1145 @@
+
+
+
+
+
+
+
+ minim.discogs - Minim 1.0.0 documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Back to top
+
+
+
+ Source code for minim.discogs
+"""
+Discogs
+=======
+.. moduleauthor:: Benjamin Ye <GitHub: bbye98>
+"""
+
+from http.server import HTTPServer, BaseHTTPRequestHandler
+import json
+import logging
+from multiprocessing import Process
+import os
+import re
+import secrets
+import time
+from typing import Any, Union
+import urllib
+import warnings
+import webbrowser
+
+import requests
+
+from . import (FOUND_FLASK, FOUND_PLAYWRIGHT, VERSION, REPOSITORY_URL,
+ DIR_HOME, DIR_TEMP, config)
+if FOUND_FLASK:
+ from . import Flask, request
+if FOUND_PLAYWRIGHT:
+ from . import sync_playwright
+
+__all__ = ["API"]
+
+class _DiscogsRedirectHandler(BaseHTTPRequestHandler):
+
+ """
+ HTTP request handler for the Discogs OAuth 1.0a flow.
+ """
+
+ def do_GET(self):
+
+ """
+ Handles an incoming GET request and parses the query string.
+ """
+
+ self.server.response = dict(
+ urllib.parse.parse_qsl(
+ urllib.parse.urlparse(f"{self.path}").query
+ )
+ )
+ self.send_response(200)
+ self.send_header("Content-Type", "text/html")
+ self.end_headers()
+ status = "denied" if "denied" in self.server.response else "granted"
+ self.wfile.write(
+ f"Access {status}. You may close this page now.".encode()
+ )
+
+
+[docs]
+class API:
+
+ """
+ Discogs API client.
+
+ The Discogs API lets developers build their own Discogs-powered
+ applications for the web, desktop, and mobile devices. It is a
+ RESTful interface to Discogs data and enables accessing JSON-
+ formatted information about artists, releases, and labels,
+ managing user collections and wantlists, creating marketplace
+ listings, and more.
+
+ .. seealso::
+
+ For more information, see the `Discogs API home page
+ <https://www.discogs.com/developers>`_.
+
+ The Discogs API can be accessed with or without authentication.
+ (client credentials, personal access token, or OAuth access token
+ and access token secret). However, it is recommended that users at
+ least provide client credentials to enjoy higher rate limits and
+ access to image URLs. The consumer key and consumer secret can
+ either be provided to this class's constructor as keyword arguments
+ or be stored as :code:`DISCOGS_CONSUMER_KEY` and
+ :code:`DISCOGS_CONSUMER_SECRET` in the operating system's
+ environment variables.
+
+ .. seealso::
+
+ To get client credentials, see the Registration section of the
+ `Authentication page <https://www.discogs.com/developers
+ /#page:authentication>`_ of the Discogs API website. To take
+ advantage of Minim's automatic access token retrieval
+ functionality for the OAuth 1.0a flow, the redirect URI should be
+ in the form :code:`http://localhost:{port}/callback`, where
+ :code:`{port}` is an open port on :code:`localhost`.
+
+ To view and make changes to account information and resources, users
+ must either provide a personal access token to this class's
+ constructor as a keyword argument or store it as
+ :code:`DISCOGS_PERSONAL_ACCESS_TOKEN` in the operating system's
+ environment variables, or undergo the OAuth 1.0a flow, which require
+ valid client credentials, using Minim. If an existing OAuth access
+ token/secret pair is available, it can be provided to this class's
+ constructor as keyword arguments to bypass the access token
+ retrieval process.
+
+ .. tip::
+
+ The authorization flow and access token can be changed or updated
+ at any time using :meth:`set_flow` and :meth:`set_access_token`,
+ respectively.
+
+ Minim also stores and manages access tokens and their properties.
+ When the OAuth 1.0a flow is used to acquire an access token/secret
+ pair, it is automatically saved to the Minim configuration file to
+ be loaded on the next instantiation of this class. This behavior can
+ be disabled if there are any security concerns, like if the computer
+ being used is a shared device.
+
+ Parameters
+ ----------
+ consumer_key : `str`, keyword-only, optional
+ Consumer key. Required for the OAuth 1.0a flow, and can be used
+ in the Discogs authorization flow alongside a consumer secret.
+ If it is not stored as :code:`DISCOGS_CONSUMER_KEY` in the
+ operating system's environment variables or found in the Minim
+ configuration file, it can be provided here.
+
+ consumer_secret : `str`, keyword-only, optional
+ Consumer secret. Required for the OAuth 1.0a flow, and can be
+ used in the Discogs authorization flow alongside a consumer key.
+ If it is not stored as :code:`DISCOGS_CONSUMER_SECRET` in the
+ operating system's environment variables or found in the Minim
+ configuration file, it can be provided here.
+
+ flow : `str`, keyword-only, optional
+ Authorization flow. If :code:`None` and no access token is
+ provided, no user authentication will be performed and client
+ credentials will not be attached to requests, even if found or
+ provided.
+
+ .. container::
+
+ **Valid values**:
+
+ * :code:`None` for no user authentication.
+ * :code:`"discogs"` for the Discogs authentication flow.
+ * :code:`"oauth"` for the OAuth 1.0a flow.
+
+ browser : `bool`, keyword-only, default: :code:`False`
+ Determines whether a web browser is automatically opened for the
+ OAuth 1.0a flow. If :code:`False`, users will have to manually
+ open the authorization URL and provide the full callback URI via
+ the terminal.
+
+ web_framework : `str`, keyword-only, optional
+ Determines which web framework to use for the OAuth 1.0a flow.
+
+ .. container::
+
+ **Valid values**:
+
+ * :code:`"http.server"` for the built-in implementation of
+ HTTP servers.
+ * :code:`"flask"` for the Flask framework.
+ * :code:`"playwright"` for the Playwright framework by
+ Microsoft.
+
+ port : `int` or `str`, keyword-only, default: :code:`8888`
+ Port on :code:`localhost` to use for the OAuth 1.0a flow with
+ the :code:`http.server` and Flask frameworks. Only used if
+ `redirect_uri` is not specified.
+
+ redirect_uri : `str`, keyword-only, optional
+ Redirect URI for the OAuth 1.0a flow. If not on
+ :code:`localhost`, the automatic request access token retrieval
+ functionality is not available.
+
+ access_token : `str`, keyword-only, optional
+ Personal or OAuth access token. If provided here or found in the
+ Minim configuration file, the authentication process is
+ bypassed.
+
+ access_token_secret : `str`, keyword-only, optional
+ OAuth access token secret accompanying `access_token`.
+
+ overwrite : `bool`, keyword-only, default: :code:`False`
+ Determines whether to overwrite an existing access token in the
+ Minim configuration file.
+
+ save : `bool`, keyword-only, default: :code:`True`
+ Determines whether newly obtained access tokens and their
+ associated properties are stored to the Minim configuration
+ file.
+
+ Attributes
+ ----------
+ API_URL : `str`
+ Base URL for the Discogs API.
+
+ ACCESS_TOKEN_URL : `str`
+ URL for the OAuth 1.0a access token endpoint.
+
+ AUTH_URL : `str`
+ URL for the OAuth 1.0a authorization endpoint.
+
+ REQUEST_TOKEN_URL : `str`
+ URL for the OAuth 1.0a request token endpoint.
+
+ session : `requests.Session`
+ Session used to send requests to the Discogs API.
+ """
+
+ _FLOWS = {"discogs", "oauth"}
+ _NAME = f"{__module__}.{__qualname__}"
+
+ API_URL = "https://api.discogs.com"
+ ACCESS_TOKEN_URL = f"{API_URL}/oauth/access_token"
+ AUTH_URL = "https://www.discogs.com/oauth/authorize"
+ REQUEST_TOKEN_URL = f"{API_URL}/oauth/request_token"
+
+ def __init__(
+ self, *, consumer_key: str = None, consumer_secret: str = None,
+ flow: str = None, browser: bool = False, web_framework: str = None,
+ port: Union[int, str] = 8888, redirect_uri: str = None,
+ access_token: str = None, access_token_secret: str = None,
+ overwrite: bool = False, save: bool = True) -> None:
+
+ """
+ Create a Discogs API client.
+ """
+
+ self.session = requests.Session()
+ self.session.headers["User-Agent"] = f"Minim/{VERSION} +{REPOSITORY_URL}"
+
+ if (access_token is None and config.has_section(self._NAME)
+ and not overwrite):
+ flow = config.get(self._NAME, "flow")
+ access_token = config.get(self._NAME, "access_token")
+ access_token_secret = config.get(self._NAME, "access_token_secret")
+ consumer_key = config.get(self._NAME, "consumer_key")
+ consumer_secret = config.get(self._NAME, "consumer_secret")
+ elif flow is None and access_token is not None:
+ flow = "discogs" if access_token_secret is None else "oauth"
+
+ self.set_flow(
+ flow, consumer_key=consumer_key, consumer_secret=consumer_secret,
+ browser=browser, web_framework=web_framework, port=port,
+ redirect_uri=redirect_uri, save=save
+ )
+ self.set_access_token(access_token, access_token_secret)
+
+ def _check_authentication(
+ self, endpoint: str, token: bool = True) -> None:
+
+ """
+ Check if the user is authenticated for the desired endpoint.
+
+ Parameters
+ ----------
+ endpoint : `str`
+ Discogs API endpoint.
+
+ token : `bool`, default: :code:`True`
+ Specifies whether a personal access token or OAuth access
+ token is required for the endpoint. If :code:`False`, only
+ client credentials are required.
+ """
+
+ if token and (
+ self._flow != "oauth"
+ or self._flow == "discogs"
+ and "token" not in self.session.headers["Authorization"]
+ ):
+ emsg = (f"{self._NAME}.{endpoint}() requires user "
+ "authentication.")
+ raise RuntimeError(emsg)
+ elif self._flow is None:
+ emsg = f"{self._NAME}.{endpoint}() requires client credentials."
+ raise RuntimeError(emsg)
+
+ def _get_json(self, url: str, **kwargs) -> dict:
+
+ """
+ Send a GET request and return the JSON-encoded content of the
+ response.
+
+ Parameters
+ ----------
+ url : `str`
+ URL for the GET request.
+
+ **kwargs
+ Keyword arguments to pass to :meth:`requests.request`.
+
+ Returns
+ -------
+ resp : `dict`
+ JSON-encoded content of the response.
+ """
+
+ return self._request("get", url, **kwargs).json()
+
+ def _request(
+ self, method: str, url: str, *, oauth: dict[str, Any] = None,
+ **kwargs) -> requests.Response:
+
+ """
+ Construct and send a request with status code checking.
+
+ Parameters
+ ----------
+ method : `str`
+ Method for the request.
+
+ url : `str`
+ URL for the request.
+
+ oauth : `dict`, keyword-only, optional
+ OAuth-related values to be included in the authorization
+ header.
+
+ **kwargs
+ Keyword arguments passed to :meth:`requests.request`.
+
+ Returns
+ -------
+ resp : `requests.Response`
+ Response to the request.
+ """
+
+ if self._flow == "oauth" \
+ and "Authorization" not in kwargs.get("headers", {}):
+ if oauth is None:
+ oauth = {}
+ oauth = self._oauth | {
+ "oauth_nonce": secrets.token_hex(32),
+ "oauth_timestamp": f"{time.time():.0f}"
+ } | oauth
+
+ if "headers" not in kwargs:
+ kwargs["headers"] = {}
+ kwargs["headers"]["Authorization"] = "OAuth " + ", ".join(
+ f'{k}="{v}"' for k, v in oauth.items()
+ )
+
+ r = self.session.request(method, url, **kwargs)
+ if r.status_code not in range(200, 299):
+ raise RuntimeError(f"{r.status_code}: {r.json()['message']}")
+ return r
+
+
+[docs]
+ def set_access_token(
+ self, access_token: str = None, access_token_secret: str = None
+ ) -> None:
+
+ """
+ Set the Discogs API personal or OAuth access token.
+
+ Parameters
+ ----------
+ access_token : `str`, optional
+ Personal or OAuth access token.
+
+ access_token_secret : `str`, optional
+ OAuth access token secret.
+ """
+
+ if self._flow == "oauth":
+ self._oauth = {
+ "oauth_consumer_key": self._consumer_key,
+ "oauth_signature_method": "PLAINTEXT"
+ }
+
+ if access_token is None:
+ oauth = {"oauth_signature": f"{self._consumer_secret}&"}
+ if self._redirect_uri is not None:
+ oauth["oauth_callback"] = self._redirect_uri
+ r = self._request(
+ "get",
+ self.REQUEST_TOKEN_URL,
+ headers={
+ "Content-Type": "application/x-www-form-urlencoded"
+ },
+ oauth=oauth
+ )
+ auth_url = f"{self.AUTH_URL}?{r.text}"
+ oauth = dict(urllib.parse.parse_qsl(r.text))
+
+ if self._web_framework == "playwright":
+ har_file = DIR_TEMP / "minim_discogs.har"
+
+ with sync_playwright() as playwright:
+ browser = playwright.firefox.launch(headless=False)
+ context = browser.new_context(record_har_path=har_file)
+ page = context.new_page()
+ page.goto(auth_url, timeout=0)
+ page.wait_for_url(f"{self._redirect_uri}*",
+ wait_until="commit")
+ context.close()
+ browser.close()
+
+ with open(har_file, "r") as f:
+ oauth |= dict(
+ urllib.parse.parse_qsl(
+ urllib.parse.urlparse(
+ re.search(f'{self._redirect_uri}\?(.*?)"',
+ f.read()).group(0)
+ ).query
+ )
+ )
+ har_file.unlink()
+
+ else:
+ if self._browser:
+ webbrowser.open(auth_url)
+ else:
+ print("To grant Minim access to Discogs data "
+ "and features, open the following link "
+ f"in your web browser:\n\n{auth_url}\n")
+
+ if self._web_framework == "http.server":
+ httpd = HTTPServer(("", self._port),
+ _DiscogsRedirectHandler)
+ httpd.handle_request()
+ oauth |= httpd.response
+
+ elif self._web_framework == "flask":
+ app = Flask(__name__)
+ json_file = DIR_TEMP / "minim_discogs.json"
+
+ @app.route("/callback", methods=["GET"])
+ def _callback() -> str:
+ if "error" in request.args:
+ return ("Access denied. You may close "
+ "this page now.")
+ with open(json_file, "w") as f:
+ json.dump(request.args, f)
+ return ("Access granted. You may close "
+ "this page now.")
+
+ server = Process(target=app.run,
+ args=("0.0.0.0", self._port))
+ server.start()
+ while not json_file.is_file():
+ time.sleep(0.1)
+ server.terminate()
+
+ with open(json_file, "rb") as f:
+ oauth |= json.load(f)
+ json_file.unlink()
+
+ else:
+ oauth["oauth_verifier"] = input(
+ "After authorizing Minim to access Discogs "
+ "on your behalf, enter the displayed code "
+ "below.\n\nCode: "
+ )
+
+ if "denied" in oauth:
+ raise RuntimeError("Authorization failed.")
+
+ oauth["oauth_signature"] = (f"{self._consumer_secret}"
+ f"&{oauth['oauth_token_secret']}")
+ r = self._request(
+ "post",
+ self.ACCESS_TOKEN_URL,
+ headers={
+ "Content-Type": "application/x-www-form-urlencoded"
+ },
+ oauth=oauth
+ )
+ access_token, access_token_secret = \
+ dict(urllib.parse.parse_qsl(r.text)).values()
+
+ if self._save:
+ config[self._NAME] = {
+ "flow": self._flow,
+ "access_token": access_token,
+ "access_token_secret": access_token_secret,
+ "consumer_key": self._consumer_key,
+ "consumer_secret": self._consumer_secret
+ }
+ with open(DIR_HOME / "minim.cfg", "w") as f:
+ config.write(f)
+
+ self._oauth |= {
+ "oauth_token": access_token,
+ "oauth_signature": self._consumer_secret
+ + f"&{access_token_secret}"
+ }
+
+ elif self._flow == "discogs":
+ access_token = \
+ access_token or os.environ.get("DISCOGS_PERSONAL_ACCESS_TOKEN")
+ if access_token is None:
+ if self._consumer_key is None or self._consumer_secret is None:
+ emsg = "Discogs API client credentials not provided."
+ raise ValueError(emsg)
+ self.session.headers["Authorization"] = (
+ f"Discogs key={self._consumer_key}, "
+ f"secret={self._consumer_secret}"
+ )
+ else:
+ self.session.headers["Authorization"] = \
+ f"Discogs token={access_token}"
+
+ if (self._flow == "oauth"
+ or self._flow == "discogs"
+ and "token" in self.session.headers["Authorization"]):
+ identity = self.get_identity()
+ self._username = identity["username"]
+
+
+
+[docs]
+ def set_flow(
+ self, flow: str, *, consumer_key: str = None,
+ consumer_secret: str = None, browser: bool = False,
+ web_framework: str = None, port: Union[int, str] = 8888,
+ redirect_uri: str = None, save: bool = True) -> None:
+
+ """
+ Set the authorization flow.
+
+ Parameters
+ ----------
+ flow : `str`
+ Authorization flow. If :code:`None`, no user authentication
+ will be performed and client credentials will not be
+ attached to requests, even if found or provided.
+
+ .. container::
+
+ **Valid values**:
+
+ * :code:`None` for no user authentication.
+ * :code:`"discogs"` for the Discogs authentication flow.
+ * :code:`"oauth"` for the OAuth 1.0a flow.
+
+ consumer_key : `str`, keyword-only, optional
+ """
+
+ if flow and flow not in self._FLOWS:
+ emsg = (f"Invalid authorization flow ({flow=}). "
+ f"Valid values: {', '.join(self._FLOWS)}.")
+ raise ValueError(emsg)
+ self._flow = flow
+ self._save = save
+
+ self._consumer_key = \
+ consumer_key or os.environ.get("DISCOGS_CONSUMER_KEY")
+ self._consumer_secret = \
+ consumer_secret or os.environ.get("DISCOGS_CONSUMER_SECRET")
+
+ if flow == "oauth":
+ self._browser = browser
+ if redirect_uri:
+ self._redirect_uri = redirect_uri
+ if "localhost" in redirect_uri:
+ self._port = re.search("localhost:(\d+)",
+ redirect_uri).group(1)
+ elif web_framework:
+ wmsg = ("The redirect URI is not on localhost, "
+ "so automatic authorization code "
+ "retrieval is not available.")
+ logging.warning(wmsg)
+ web_framework = None
+ elif port:
+ self._port = port
+ self._redirect_uri = f"http://localhost:{port}/callback"
+ else:
+ self._port = self._redirect_uri = None
+
+ self._web_framework = (
+ web_framework
+ if web_framework is None
+ or web_framework == "http.server"
+ or globals()[f"FOUND_{web_framework.upper()}"]
+ else None
+ )
+ if self._web_framework is None and web_framework:
+ wmsg = (f"The {web_framework.capitalize()} web "
+ "framework was not found, so automatic "
+ "authorization code retrieval is not "
+ "available.")
+ warnings.warn(wmsg)
+
+
+ ### DATABASE ##############################################################
+
+ ### MARKETPLACE ###########################################################
+
+ ### INVENTORY EXPORT ######################################################
+
+ ### INVENTORY UPLOAD ######################################################
+
+ ### USER IDENTITY #########################################################
+
+
+[docs]
+ def get_identity(self) -> dict[str, Any]:
+
+ """
+ `User Identity > Identity <https://www.discogs.com/developers
+ /#page:user-identity,header:user-identity-identity-get>`_:
+ Retrieve basic information about the authenticated user.
+
+ .. admonition:: User authentication
+ :class: warning
+
+ Requires user authentication with a personal access token or
+ via the OAuth 1.0a flow.
+
+ You can use this resource to find out who you're authenticated
+ as, and it also doubles as a good sanity check to ensure that
+ you're using OAuth correctly.
+
+ For more detailed information, make another request for the
+ user's profile using :meth:`get_profile`.
+
+ Returns
+ -------
+ identity : `dict`
+ Basic information about the authenticated user.
+
+ .. admonition:: Sample
+ :class: dropdown
+
+ .. code::
+
+ {
+ "id": <int>,
+ "username": <str>,
+ "resource_url": <str>,
+ "consumer_name": <str>
+ }
+ """
+
+ self._check_authentication("get_identity")
+
+ return self._get_json(f"{self.API_URL}/oauth/identity")
+
+
+
+[docs]
+ def get_profile(self, username: str = None) -> dict[str, Any]:
+
+ """
+ `User Identity > Profile > Get Profile
+ <https://www.discogs.com/developers
+ /#page:user-identity,header:user-identity-profile-get>`_:
+ Retrieve a user by username.
+
+ If authenticated as the requested user, the :code:`"email"` key
+ will be visible, and the :code:`"num_lists"` count will include
+ the user's private lists.
+
+ If authenticated as the requested user or the user's
+ collection/wantlist is public, the
+ :code:`"num_collection"`/:code:`"num_wantlist"` keys will be
+ visible.
+
+ Parameters
+ ----------
+ username : `str`, optional
+ The username of whose profile you are requesting. If not
+ specified, the profile of the authenticated user is used.
+
+ **Example**: :code:`"rodneyfool"`.
+
+ Returns
+ -------
+ profile : `dict`
+ Detailed information about the user.
+
+ .. admonition:: Sample
+ :class: dropdown
+
+ .. code::
+
+ {
+ "profile": <str>,
+ "wantlist_url": <str>,
+ "rank": <int>,
+ "num_pending": <int>,
+ "id": <int>,
+ "num_for_sale": <int>,
+ "home_page": <str>,
+ "location": <str>,
+ "collection_folders_url": <str>,
+ "username": <str>,
+ "collection_fields_url": <str>,
+ "releases_contributed": <int>,
+ "registered": <str>,
+ "rating_avg": <float>,
+ "num_collection": <int>,
+ "releases_rated": <int>,
+ "num_lists": <int>,
+ "name": <str>,
+ "num_wantlist": <int>,
+ "inventory_url": <str>,
+ "avatar_url": <str>,
+ "banner_url": <str>,
+ "uri": <str>,
+ "resource_url": <str>,
+ "buyer_rating": <float>,
+ "buyer_rating_stars": <int>,
+ "buyer_num_ratings": <int>,
+ "seller_rating": <float>,
+ "seller_rating_stars": <int>,
+ "seller_num_ratings": <int>,
+ "curr_abbr": <str>,
+ }
+ """
+
+ if username is None:
+ if hasattr(self, "_username"):
+ username = self._username
+ else:
+ raise ValueError("No username provided.")
+ return self._get_json(f"{self.API_URL}/users/{username}")
+
+
+
+[docs]
+ def edit_profile(
+ self, *, name: str = None, home_page: str = None,
+ location: str = None, profile: str = None,
+ curr_abbr: str = None) -> dict[str, Any]:
+
+ """
+ `User Identity > Profile > Edit Profile
+ <https://www.discogs.com/developers
+ /#page:user-identity,header:user-identity-profile-post>`_:
+ Edit a user's profile data.
+
+ .. admonition:: User authentication
+ :class: warning
+
+ Requires user authentication with a personal access token or
+ via the OAuth 1.0a flow.
+
+ Parameters
+ ----------
+ name : `str`, keyword-only, optional
+ The real name of the user.
+
+ **Example**: :code:`"Nicolas Cage"`.
+
+ home_page : `str`, keyword-only, optional
+ The user's website.
+
+ **Example**: :code:`"www.discogs.com"`.
+
+ location : `str`, keyword-only, optional
+ The geographical location of the user.
+
+ **Example**: :code:`"Portland"`.
+
+ profile : `str`, keyword-only, optional
+ Biological information about the user.
+
+ **Example**: :code:`"I am a Discogs user!"`.
+
+ curr_abbr : `str`, keyword-only, optional
+ Currency abbreviation for marketplace data.
+
+ **Valid values**: :code:`"USD"`, :code:`"GBP"`,
+ :code:`"EUR"`, :code:`"CAD"`, :code:`"AUD"`, :code:`"JPY"`,
+ :code:`"CHF"`, :code:`"MXN"`, :code:`"BRL"`, :code:`"NZD"`,
+ :code:`"SEK"`, and :code:`"ZAR"`.
+
+ Returns
+ -------
+ profile : `dict`
+ Updated profile.
+
+ .. admonition:: Sample
+ :class: dropdown
+
+ .. code::
+
+ {
+ "id": <int>,
+ "username": <str>,
+ "name": <str>,
+ "email": <str>,
+ "resource_url": <str>,
+ "inventory_url": <str>,
+ "collection_folders_url": <str>,
+ "collection_fields_url": <str>,
+ "wantlist_url": <str>,
+ "uri": <str>,
+ "profile": <str>,
+ "home_page": <str>,
+ "location": <str>,
+ "registered": <str>,
+ "num_lists": <int>,
+ "num_for_sale": <int>,
+ "num_collection": <int>,
+ "num_wantlist": <int>,
+ "num_pending": <int>,
+ "releases_contributed": <int>,
+ "rank": <int>,
+ "releases_rated": <int>,
+ "rating_avg": <float>
+ }
+ """
+
+ self._check_authentication("edit_profile")
+
+ return self._request(
+ "post",
+ f"{self.API_URL}/users/{self._username}",
+ json={
+ "name": name,
+ "home_page": home_page,
+ "location": location,
+ "profile": profile,
+ "curr_abbr": curr_abbr
+ }
+ ).json()
+
+
+
+[docs]
+ def get_user_submissions(
+ self, username: str, *, page: int = None, per_page: int = None
+ ) -> dict[str, Any]:
+
+ """
+
+ """
+
+ pass
+
+
+
+[docs]
+ def get_user_contributions(
+ self, username: str, *, page: int = None, per_page: int = None,
+ sort: str = None, sort_order: str = None) -> dict[str, Any]:
+
+ """
+
+ """
+
+ pass
+
+
+
+ ### USER COLLECTION #######################################################
+
+ ### USER WANTLIST #########################################################
+
+ ### USER LISTS ############################################################
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/minim/itunes.html b/docs/_modules/minim/itunes.html
index 3d2fecc..7a93296 100644
--- a/docs/_modules/minim/itunes.html
+++ b/docs/_modules/minim/itunes.html
@@ -176,28 +176,32 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
@@ -245,7 +249,8 @@
Source code for minim.itunes
endpoints.
"""
-from . import requests, Any, Union
+import requests
+from typing import Any, Union
__all__ = ["SearchAPI"]
diff --git a/docs/_modules/minim/qobuz.html b/docs/_modules/minim/qobuz.html
index 6fb576b..e7fccd6 100644
--- a/docs/_modules/minim/qobuz.html
+++ b/docs/_modules/minim/qobuz.html
@@ -176,28 +176,32 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
@@ -244,11 +248,17 @@
Source code for minim.qobuz
This module contains a minimum implementation of the private Qobuz API.
"""
-from . import (
- base64, datetime, hashlib, logging, os, re, requests,
- FOUND_PLAYWRIGHT, DIR_HOME, DIR_TEMP, Any, Union, config
-)
+import base64
+import datetime
+import hashlib
+import logging
+import os
+import re
+from typing import Any, Union
+
+import requests
+from . import FOUND_PLAYWRIGHT, DIR_HOME, DIR_TEMP, config
if FOUND_PLAYWRIGHT:
from . import sync_playwright
@@ -497,7 +507,7 @@ Source code for minim.qobuz
def _request(self, method: str, url: str, **kwargs) -> requests.Response:
"""
- Construct and send a request, but with status code checking.
+ Construct and send a request with status code checking.
Parameters
----------
@@ -700,7 +710,7 @@ Source code for minim.qobuz
app_id = app_id or os.environ.get("QOBUZ_PRIVATE_APP_ID")
app_secret = app_secret or os.environ.get("QOBUZ_PRIVATE_APP_SECRET")
- if (not app_id or not app_secret) and auth_token:
+ if (app_id is None or app_secret is None) and auth_token is not None:
emsg = ("App credentials are required when an user "
"authentication token is provided.")
diff --git a/docs/_modules/minim/spotify.html b/docs/_modules/minim/spotify.html
index c868299..f2e4cee 100644
--- a/docs/_modules/minim/spotify.html
+++ b/docs/_modules/minim/spotify.html
@@ -176,28 +176,32 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
@@ -246,21 +250,27 @@
Source code for minim.spotify
service.
"""
+import base64
+import datetime
+import hashlib
from http.server import HTTPServer, BaseHTTPRequestHandler
+import json
+import logging
from multiprocessing import Process
-
-try:
- from flask import Flask, request
- FOUND_FLASK = True
-except ModuleNotFoundError:
- FOUND_FLASK = False
-
-from . import (
- base64, datetime, hashlib, json, logging, os, re, requests, secrets, time,
- urllib, warnings, webbrowser,
- FOUND_PLAYWRIGHT, DIR_HOME, DIR_TEMP, Any, Union, config
-)
-
+import os
+import re
+import secrets
+import time
+from typing import Any, Union
+import urllib
+import warnings
+import webbrowser
+
+import requests
+
+from . import FOUND_FLASK, FOUND_PLAYWRIGHT, DIR_HOME, DIR_TEMP, config
+if FOUND_FLASK:
+ from . import Flask, request
if FOUND_PLAYWRIGHT:
from . import sync_playwright
@@ -287,7 +297,9 @@ Source code for minim.spotify
self.send_header("Content-Type", "text/html")
self.end_headers()
status = "denied" if "error" in self.server.response else "granted"
- self.wfile.write(f"Access {status}. You may close this page now.".encode())
+ self.wfile.write(
+ f"Access {status}. You may close this page now.".encode()
+ )
[docs]
@@ -428,7 +440,7 @@ Source code for minim.spotify
) -> requests.Response:
"""
- Construct and send a request, but with status code checking.
+ Construct and send a request with status code checking.
Parameters
----------
@@ -717,7 +729,7 @@ Source code for minim.spotify
* :code:`"web_player"` for a Spotify Web Player access
token.
- framework : `str`, keyword-only, optional
+ web_framework : `str`, keyword-only, optional
Determines which web framework to use for the authorization code
flow.
@@ -733,8 +745,8 @@ Source code for minim.spotify
port : `int` or `str`, keyword-only, default: :code:`8888`
Port on :code:`localhost` to use for the authorization code
- flow with the Flask framework. Only used if `redirect_uri` is
- not specified.
+ flow with the :code:`http.server` and Flask frameworks. Only
+ used if `redirect_uri` is not specified.
redirect_uri : `str`, keyword-only, optional
Redirect URI for the authorization code flow. If not on
@@ -919,7 +931,7 @@ Source code for minim.spotify
def __init__(
self, *, client_id: str = None, client_secret: str = None,
- flow: str = "web_player", framework: str = None,
+ flow: str = "web_player", web_framework: str = None,
port: Union[int, str] = 8888, redirect_uri: str = None,
scopes: Union[str, list[str]] = "", sp_dc: str = None,
access_token: str = None, refresh_token: str = None,
@@ -949,7 +961,7 @@ Source code for minim.spotify
self.set_flow(
flow, client_id=client_id, client_secret=client_secret,
- framework=framework, port=port, redirect_uri=redirect_uri,
+ web_framework=web_framework, port=port, redirect_uri=redirect_uri,
scopes=scopes, sp_dc=sp_dc, save=save
)
self.set_access_token(access_token, refresh_token=refresh_token,
@@ -1005,13 +1017,13 @@ Source code for minim.spotify
params["code_challenge_method"] = "S256"
auth_url = f"{self.AUTH_URL}?{urllib.parse.urlencode(params)}"
- if self._framework == "http.server":
+ if self._web_framework == "http.server":
httpd = HTTPServer(("", self._port), _SpotifyRedirectHandler)
webbrowser.open(auth_url)
httpd.handle_request()
queries = httpd.response
- elif self._framework == "flask":
+ elif self._web_framework == "flask":
app = Flask(__name__)
json_file = DIR_TEMP / "minim_spotify.json"
@@ -1034,7 +1046,7 @@ Source code for minim.spotify
queries = json.load(f)
json_file.unlink()
- elif self._framework == "playwright":
+ elif self._web_framework == "playwright":
har_file = DIR_TEMP / "minim_spotify.har"
with sync_playwright() as playwright:
@@ -1140,7 +1152,7 @@ Source code for minim.spotify
) -> requests.Response:
"""
- Construct and send a request, but with status code checking.
+ Construct and send a request with status code checking.
Parameters
----------
@@ -1297,7 +1309,7 @@ Source code for minim.spotify
[docs]
def set_flow(
self, flow: str, *, client_id: str = None,
- client_secret: str = None, framework: str = None,
+ client_secret: str = None, web_framework: str = None,
port: Union[int, str] = 8888, redirect_uri: str = None,
scopes: Union[str, list[str]] = "", sp_dc: str = None,
save: bool = True) -> None:
@@ -1330,7 +1342,7 @@ Source code for minim.spotify
Client secret. Required for all OAuth 2.0 authorization
flows.
- framework : `str`, keyword-only, optional
+ web_framework : `str`, keyword-only, optional
Web framework used to automatically complete the
authorization code flow.
@@ -1345,7 +1357,7 @@ Source code for minim.spotify
port : `int` or `str`, keyword-only, default: :code:`8888`
Port on :code:`localhost` to use for the authorization code
- flow with the Flask framework.
+ flow with the :code:`http.server` and Flask frameworks.
redirect_uri : `str`, keyword-only, optional
Redirect URI for the authorization code flow. If not
@@ -1387,24 +1399,24 @@ Source code for minim.spotify
if "localhost" in redirect_uri:
self._port = re.search("localhost:(\d+)",
redirect_uri).group(1)
- elif framework:
+ elif web_framework:
wmsg = ("The redirect URI is not on localhost, "
"so automatic authorization code "
"retrieval is not available.")
logging.warning(wmsg)
- framework = None
+ web_framework = None
else:
self._port = port
self._redirect_uri = f"http://localhost:{port}/callback"
- self._framework = (
- framework if framework is None
- or framework == "http.server"
- or globals()[f"FOUND_{framework.upper()}"]
+ self._web_framework = (
+ web_framework if web_framework is None
+ or web_framework == "http.server"
+ or globals()[f"FOUND_{web_framework.upper()}"]
else None
)
- if self._framework is None and framework:
- wmsg = (f"The {framework.capitalize()} web "
+ if self._web_framework is None and web_framework:
+ wmsg = (f"The {web_framework.capitalize()} web "
"framework was not found, so automatic "
"authorization code retrieval is not "
"available.")
@@ -2801,8 +2813,8 @@ Source code for minim.spotify
"""
`Audiobooks > Get an Audiobook
<https://developer.spotify.com/documentation/web-api/reference/
- get-an-audiobook>`_: Get Spotify catalog
- information for a single audiobook.
+ get-an-audiobook>`_: Get Spotify catalog information for a
+ single audiobook.
.. note::
diff --git a/docs/_modules/minim/tidal.html b/docs/_modules/minim/tidal.html
index 3415b4c..bdb14e9 100644
--- a/docs/_modules/minim/tidal.html
+++ b/docs/_modules/minim/tidal.html
@@ -176,28 +176,32 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
@@ -246,16 +250,26 @@
Source code for minim.tidal
TIDAL API.
"""
+import base64
+import datetime
+import hashlib
+import json
+import logging
+import os
+import pathlib
+import re
+import secrets
+import time
+from typing import Any, Union
+import urllib
+import warnings
+import webbrowser
from xml.dom import minidom
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+import requests
-from . import (
- base64, datetime, hashlib, json, logging, os, pathlib, re, requests,
- secrets, time, urllib, warnings, webbrowser,
- FOUND_PLAYWRIGHT, DIR_HOME, DIR_TEMP, Any, Union, config
-)
-
+from . import FOUND_PLAYWRIGHT, DIR_HOME, DIR_TEMP, config
if FOUND_PLAYWRIGHT:
from . import sync_playwright
@@ -423,7 +437,7 @@ Source code for minim.tidal
def _request(self, method: str, url: str, **kwargs) -> requests.Response:
"""
- Construct and send a request, but with status code checking.
+ Construct and send a request with status code checking.
Parameters
----------
@@ -2524,7 +2538,7 @@ Source code for minim.tidal
) -> requests.Response:
"""
- Construct and send a request, but with status code checking.
+ Construct and send a request with status code checking.
Parameters
----------
diff --git a/docs/_modules/minim/utility.html b/docs/_modules/minim/utility.html
index 2260c0a..cd569ff 100644
--- a/docs/_modules/minim/utility.html
+++ b/docs/_modules/minim/utility.html
@@ -173,29 +173,32 @@
- FLACAudio
- MP3Audio
- MP4Audio
-- OggAudio
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
@@ -246,8 +249,7 @@ Source code for minim.utility
"""
from difflib import SequenceMatcher
-
-from . import Any, Union
+from typing import Any, Union
try:
import Levenshtein
diff --git a/docs/_sources/api/minim.discogs.API.rst.txt b/docs/_sources/api/minim.discogs.API.rst.txt
new file mode 100644
index 0000000..23e31a7
--- /dev/null
+++ b/docs/_sources/api/minim.discogs.API.rst.txt
@@ -0,0 +1,27 @@
+API
+===
+
+.. currentmodule:: minim.discogs
+
+.. autoclass:: API
+ :members:
+ :show-inheritance:
+ :inherited-members:
+ :special-members: __call__, __add__, __mul__
+
+
+
+ .. rubric:: Methods
+
+ .. autosummary::
+ :nosignatures:
+
+ ~API.edit_profile
+ ~API.get_identity
+ ~API.get_profile
+ ~API.get_user_contributions
+ ~API.get_user_submissions
+ ~API.set_access_token
+ ~API.set_flow
+
+
\ No newline at end of file
diff --git a/docs/_sources/api/minim.discogs.rst.txt b/docs/_sources/api/minim.discogs.rst.txt
new file mode 100644
index 0000000..bfb5edd
--- /dev/null
+++ b/docs/_sources/api/minim.discogs.rst.txt
@@ -0,0 +1,32 @@
+discogs
+=======
+
+.. automodule:: minim.discogs
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+ :toctree:
+ :template: autosummary/class.rst
+ :nosignatures:
+
+ API
+
+
+
+
+
+
+
+
+
diff --git a/docs/_sources/api/minim.rst.txt b/docs/_sources/api/minim.rst.txt
index a1aa4a2..bcd91e2 100644
--- a/docs/_sources/api/minim.rst.txt
+++ b/docs/_sources/api/minim.rst.txt
@@ -27,6 +27,7 @@
:recursive:
minim.audio
+ minim.discogs
minim.itunes
minim.qobuz
minim.spotify
diff --git a/docs/_sources/notebooks/user_guide/transferring_music_libraries.ipynb.txt b/docs/_sources/notebooks/user_guide/transferring_music_libraries.ipynb.txt
index 0fbee20..4a62223 100644
--- a/docs/_sources/notebooks/user_guide/transferring_music_libraries.ipynb.txt
+++ b/docs/_sources/notebooks/user_guide/transferring_music_libraries.ipynb.txt
@@ -38,7 +38,7 @@
"client_qobuz = qobuz.PrivateAPI(flow=\"password\", browser=True)\n",
"client_spotify = spotify.WebAPI(flow=\"pkce\", \n",
" scopes=spotify.WebAPI.get_scopes(\"all\"),\n",
- " framework=\"http.server\")\n",
+ " web_framework=\"http.server\")\n",
"client_tidal = tidal.PrivateAPI(flow=\"device\", browser=True)"
]
},
diff --git a/docs/api.html b/docs/api.html
index d9ae78f..79172f5 100644
--- a/docs/api.html
+++ b/docs/api.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.audio.Audio.html b/docs/api/minim.audio.Audio.html
index b5dd2d6..5d1f41c 100644
--- a/docs/api/minim.audio.Audio.html
+++ b/docs/api/minim.audio.Audio.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.audio.FLACAudio.html b/docs/api/minim.audio.FLACAudio.html
index 587b364..f180c1c 100644
--- a/docs/api/minim.audio.FLACAudio.html
+++ b/docs/api/minim.audio.FLACAudio.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.audio.MP3Audio.html b/docs/api/minim.audio.MP3Audio.html
index 2f2bfd8..acf30b3 100644
--- a/docs/api/minim.audio.MP3Audio.html
+++ b/docs/api/minim.audio.MP3Audio.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.audio.MP4Audio.html b/docs/api/minim.audio.MP4Audio.html
index 33cf686..2efe754 100644
--- a/docs/api/minim.audio.MP4Audio.html
+++ b/docs/api/minim.audio.MP4Audio.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.audio.OGGAudio.html b/docs/api/minim.audio.OGGAudio.html
index 2d3105d..5640ee7 100644
--- a/docs/api/minim.audio.OGGAudio.html
+++ b/docs/api/minim.audio.OGGAudio.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.audio.WAVEAudio.html b/docs/api/minim.audio.WAVEAudio.html
index d9d7353..4418c89 100644
--- a/docs/api/minim.audio.WAVEAudio.html
+++ b/docs/api/minim.audio.WAVEAudio.html
@@ -3,7 +3,7 @@
-
+
WAVEAudio - Minim 1.0.0 documentation
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
@@ -548,12 +552,12 @@ WAVEAudio
-
+
Next
- itunes
+ discogs
diff --git a/docs/api/minim.audio.html b/docs/api/minim.audio.html
index 5069b5f..c5014fb 100644
--- a/docs/api/minim.audio.html
+++ b/docs/api/minim.audio.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.discogs.API.html b/docs/api/minim.discogs.API.html
new file mode 100644
index 0000000..7cb4dd0
--- /dev/null
+++ b/docs/api/minim.discogs.API.html
@@ -0,0 +1,733 @@
+
+
+
+
+
+
+
+
+ API - Minim 1.0.0 documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Back to top
+
+
+
+
+API#
+
+-
+class minim.discogs.API(*, consumer_key: str = None, consumer_secret: str = None, flow: str = None, browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, access_token: str = None, access_token_secret: str = None, overwrite: bool = False, save: bool = True)[source]#
+Bases: object
+Discogs API client.
+The Discogs API lets developers build their own Discogs-powered
+applications for the web, desktop, and mobile devices. It is a
+RESTful interface to Discogs data and enables accessing JSON-
+formatted information about artists, releases, and labels,
+managing user collections and wantlists, creating marketplace
+listings, and more.
+
+See also
+For more information, see the Discogs API home page.
+
+The Discogs API can be accessed with or without authentication.
+(client credentials, personal access token, or OAuth access token
+and access token secret). However, it is recommended that users at
+least provide client credentials to enjoy higher rate limits and
+access to image URLs. The consumer key and consumer secret can
+either be provided to this class’s constructor as keyword arguments
+or be stored as DISCOGS_CONSUMER_KEY and
+DISCOGS_CONSUMER_SECRET in the operating system’s
+environment variables.
+
+See also
+To get client credentials, see the Registration section of the
+Authentication page of the Discogs API website. To take
+advantage of Minim’s automatic access token retrieval
+functionality for the OAuth 1.0a flow, the redirect URI should be
+in the form http://localhost:{port}/callback, where
+{port} is an open port on localhost.
+
+To view and make changes to account information and resources, users
+must either provide a personal access token to this class’s
+constructor as a keyword argument or store it as
+DISCOGS_PERSONAL_ACCESS_TOKEN in the operating system’s
+environment variables, or undergo the OAuth 1.0a flow, which require
+valid client credentials, using Minim. If an existing OAuth access
+token/secret pair is available, it can be provided to this class’s
+constructor as keyword arguments to bypass the access token
+retrieval process.
+
+Tip
+The authorization flow and access token can be changed or updated
+at any time using set_flow() and set_access_token(),
+respectively.
+
+Minim also stores and manages access tokens and their properties.
+When the OAuth 1.0a flow is used to acquire an access token/secret
+pair, it is automatically saved to the Minim configuration file to
+be loaded on the next instantiation of this class. This behavior can
+be disabled if there are any security concerns, like if the computer
+being used is a shared device.
+
+- Parameters:
+
+- consumer_keystr, keyword-only, optional
Consumer key. Required for the OAuth 1.0a flow, and can be used
+in the Discogs authorization flow alongside a consumer secret.
+If it is not stored as DISCOGS_CONSUMER_KEY in the
+operating system’s environment variables or found in the Minim
+configuration file, it can be provided here.
+- consumer_secretstr, keyword-only, optional
Consumer secret. Required for the OAuth 1.0a flow, and can be
+used in the Discogs authorization flow alongside a consumer key.
+If it is not stored as DISCOGS_CONSUMER_SECRET in the
+operating system’s environment variables or found in the Minim
+configuration file, it can be provided here.
+- flowstr, keyword-only, optional
Authorization flow. If None and no access token is
+provided, no user authentication will be performed and client
+credentials will not be attached to requests, even if found or
+provided.
+
+Valid values:
+
+None for no user authentication.
"discogs" for the Discogs authentication flow.
"oauth" for the OAuth 1.0a flow.
+
+- browserbool, keyword-only, default:
False Determines whether a web browser is automatically opened for the
+OAuth 1.0a flow. If False, users will have to manually
+open the authorization URL and provide the full callback URI via
+the terminal.
+- web_frameworkstr, keyword-only, optional
Determines which web framework to use for the OAuth 1.0a flow.
+
+Valid values:
+
+"http.server" for the built-in implementation of
+HTTP servers.
"flask" for the Flask framework.
"playwright" for the Playwright framework by
+Microsoft.
+
+- portint or str, keyword-only, default:
8888 Port on localhost to use for the OAuth 1.0a flow with
+the http.server and Flask frameworks. Only used if
+redirect_uri is not specified.
+- redirect_uristr, keyword-only, optional
Redirect URI for the OAuth 1.0a flow. If not on
+localhost, the automatic request access token retrieval
+functionality is not available.
+- access_tokenstr, keyword-only, optional
Personal or OAuth access token. If provided here or found in the
+Minim configuration file, the authentication process is
+bypassed.
+- access_token_secretstr, keyword-only, optional
OAuth access token secret accompanying access_token.
+- overwritebool, keyword-only, default:
False Determines whether to overwrite an existing access token in the
+Minim configuration file.
+- savebool, keyword-only, default:
True Determines whether newly obtained access tokens and their
+associated properties are stored to the Minim configuration
+file.
+
+- Attributes:
+
+- API_URLstr
Base URL for the Discogs API.
+- ACCESS_TOKEN_URLstr
URL for the OAuth 1.0a access token endpoint.
+- AUTH_URLstr
URL for the OAuth 1.0a authorization endpoint.
+- REQUEST_TOKEN_URLstr
URL for the OAuth 1.0a request token endpoint.
+- sessionrequests.Session
Session used to send requests to the Discogs API.
+
+
+Methods
+
+
+
+User Identity > Profile > Edit Profile: Edit a user's profile data.
User Identity > Identity: Retrieve basic information about the authenticated user.
User Identity > Profile > Get Profile: Retrieve a user by username.
Set the Discogs API personal or OAuth access token.
Set the authorization flow.
+
+
+-
+set_access_token(access_token: str = None, access_token_secret: str = None) None[source]#
+Set the Discogs API personal or OAuth access token.
+
+- Parameters:
+
+- access_tokenstr, optional
Personal or OAuth access token.
+- access_token_secretstr, optional
OAuth access token secret.
+
+
+
+
+
+-
+set_flow(flow: str, *, consumer_key: str = None, consumer_secret: str = None, browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, save: bool = True) None[source]#
+Set the authorization flow.
+
+- Parameters:
+
+- flowstr
Authorization flow. If None, no user authentication
+will be performed and client credentials will not be
+attached to requests, even if found or provided.
+
+Valid values:
+
+None for no user authentication.
"discogs" for the Discogs authentication flow.
"oauth" for the OAuth 1.0a flow.
+
+- consumer_keystr, keyword-only, optional
+
+
+
+
+
+-
+get_identity() dict[str, Any][source]#
+User Identity > Identity:
+Retrieve basic information about the authenticated user.
+
+User authentication
+Requires user authentication with a personal access token or
+via the OAuth 1.0a flow.
+
+You can use this resource to find out who you’re authenticated
+as, and it also doubles as a good sanity check to ensure that
+you’re using OAuth correctly.
+For more detailed information, make another request for the
+user’s profile using get_profile().
+
+- Returns:
+
+- identitydict
Basic information about the authenticated user.
+
+Sample
+{
+ "id": <int>,
+ "username": <str>,
+ "resource_url": <str>,
+ "consumer_name": <str>
+}
+
+
+
+
+
+
+
+
+-
+get_profile(username: str = None) dict[str, Any][source]#
+User Identity > Profile > Get Profile:
+Retrieve a user by username.
+If authenticated as the requested user, the "email" key
+will be visible, and the "num_lists" count will include
+the user’s private lists.
+If authenticated as the requested user or the user’s
+collection/wantlist is public, the
+"num_collection"/"num_wantlist" keys will be
+visible.
+
+- Parameters:
+
+- usernamestr, optional
The username of whose profile you are requesting. If not
+specified, the profile of the authenticated user is used.
+Example: "rodneyfool".
+
+- Returns:
+
+- profiledict
Detailed information about the user.
+
+Sample
+{
+ "profile": <str>,
+ "wantlist_url": <str>,
+ "rank": <int>,
+ "num_pending": <int>,
+ "id": <int>,
+ "num_for_sale": <int>,
+ "home_page": <str>,
+ "location": <str>,
+ "collection_folders_url": <str>,
+ "username": <str>,
+ "collection_fields_url": <str>,
+ "releases_contributed": <int>,
+ "registered": <str>,
+ "rating_avg": <float>,
+ "num_collection": <int>,
+ "releases_rated": <int>,
+ "num_lists": <int>,
+ "name": <str>,
+ "num_wantlist": <int>,
+ "inventory_url": <str>,
+ "avatar_url": <str>,
+ "banner_url": <str>,
+ "uri": <str>,
+ "resource_url": <str>,
+ "buyer_rating": <float>,
+ "buyer_rating_stars": <int>,
+ "buyer_num_ratings": <int>,
+ "seller_rating": <float>,
+ "seller_rating_stars": <int>,
+ "seller_num_ratings": <int>,
+ "curr_abbr": <str>,
+}
+
+
+
+
+
+
+
+
+-
+edit_profile(*, name: str = None, home_page: str = None, location: str = None, profile: str = None, curr_abbr: str = None) dict[str, Any][source]#
+User Identity > Profile > Edit Profile:
+Edit a user’s profile data.
+
+User authentication
+Requires user authentication with a personal access token or
+via the OAuth 1.0a flow.
+
+
+- Parameters:
+
+- namestr, keyword-only, optional
The real name of the user.
+Example: "Nicolas Cage".
+- home_pagestr, keyword-only, optional
The user’s website.
+Example: "www.discogs.com".
+- locationstr, keyword-only, optional
The geographical location of the user.
+Example: "Portland".
+- profilestr, keyword-only, optional
Biological information about the user.
+Example: "I am a Discogs user!".
+- curr_abbrstr, keyword-only, optional
Currency abbreviation for marketplace data.
+Valid values: "USD", "GBP",
+"EUR", "CAD", "AUD", "JPY",
+"CHF", "MXN", "BRL", "NZD",
+"SEK", and "ZAR".
+
+- Returns:
+
+- profiledict
Updated profile.
+
+Sample
+{
+ "id": <int>,
+ "username": <str>,
+ "name": <str>,
+ "email": <str>,
+ "resource_url": <str>,
+ "inventory_url": <str>,
+ "collection_folders_url": <str>,
+ "collection_fields_url": <str>,
+ "wantlist_url": <str>,
+ "uri": <str>,
+ "profile": <str>,
+ "home_page": <str>,
+ "location": <str>,
+ "registered": <str>,
+ "num_lists": <int>,
+ "num_for_sale": <int>,
+ "num_collection": <int>,
+ "num_wantlist": <int>,
+ "num_pending": <int>,
+ "releases_contributed": <int>,
+ "rank": <int>,
+ "releases_rated": <int>,
+ "rating_avg": <float>
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/api/minim.discogs.html b/docs/api/minim.discogs.html
new file mode 100644
index 0000000..e11f4a1
--- /dev/null
+++ b/docs/api/minim.discogs.html
@@ -0,0 +1,343 @@
+
+
+
+
+
+
+
+
+ discogs - Minim 1.0.0 documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Back to top
+
+
+
+
+discogs#
+
+Discogs#
+
+Classes
+
+
+
+Discogs API client.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/api/minim.html b/docs/api/minim.html
index 19a7ba0..3a099d7 100644
--- a/docs/api/minim.html
+++ b/docs/api/minim.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
@@ -246,19 +250,22 @@
Audio file objects
Discogs
iTunes
Qobuz
Spotify
TIDAL
Utility functions
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.itunes.html b/docs/api/minim.itunes.html
index 307e3e5..4e099d8 100644
--- a/docs/api/minim.itunes.html
+++ b/docs/api/minim.itunes.html
@@ -3,7 +3,7 @@
-
+
itunes - Minim 1.0.0 documentation
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
@@ -271,14 +275,14 @@ iTunes#
-
+
Previous
- WAVEAudio
+ API
diff --git a/docs/api/minim.qobuz.PrivateAPI.html b/docs/api/minim.qobuz.PrivateAPI.html
index 4bc474b..9d2513a 100644
--- a/docs/api/minim.qobuz.PrivateAPI.html
+++ b/docs/api/minim.qobuz.PrivateAPI.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.qobuz.html b/docs/api/minim.qobuz.html
index 6660c01..4075c34 100644
--- a/docs/api/minim.qobuz.html
+++ b/docs/api/minim.qobuz.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes
+- discogs
+- API
+
+
+- itunes
-- qobuz
+- qobuz
-- spotify
+- spotify
-- tidal
+- tidal
-- utility
+- utility
- format_multivalue
- gestalt_ratio
- levenshtein_ratio
diff --git a/docs/api/minim.spotify.PrivateLyricsService.html b/docs/api/minim.spotify.PrivateLyricsService.html
index 48b7a5c..d539d63 100644
--- a/docs/api/minim.spotify.PrivateLyricsService.html
+++ b/docs/api/minim.spotify.PrivateLyricsService.html
@@ -178,25 +178,29 @@
- WAVEAudio
-- itunes