sdss_brain Reference¶
Api¶
- class sdss_brain.api.manager.ApiManager[source]¶
Bases:
object
Class for managing SDSS APIs
This class provides an interface for handling and managing the selection of various SDSS APIs. It allows toggling of the current API to use for all remote requests.
- Variables
domains (dict) – A dictionary of available SDSS domains
apis (dict) – A dictionary of available SDSS APIs
profile (Type[ApiProfile]) – The currently selected API to use
- display(value: str, pprint: bool = False, show_docs: bool = True, show_desc: bool = True, **kwargs) Table [source]¶
Display the APIs or domains as an Astropy Table
Display the list of available SDSS APIs or domains as an Astropy Table.
- Parameters
value (str) – Either “api(s)” or “domain(s)”
pprint (bool, optional) – If True, pretty print the Astropy Table, by default False
show_docs (bool, optional) – If True, include the “docs” column in the API table, by default True
show_desc (bool, optional) – If True, include the “description” column in the API table, by default True
kwargs (Any) – Other kwargs for Table.pprint (pretty print) method
- Returns
Table
– An Astropy Table of information- Raises
TypeError – when the input value is not a string
ValueError – when the input value is not either “apis” or “domains”
- generate_rst_table(value: str, show_docs: bool = True, show_desc: bool = True, **kwargs) str [source]¶
Generate a rst-formatted table
Generates an rst-formatted table of the available domains or APIs using the tabulate python package. This method is good for dropping tables into Sphinx documentation.
- Parameters
- Returns
str – The rst formatted table as a string
- Raises
ImportError – when the tabulate package is not installed.
- identify_api_from_url(url: str) tuple [source]¶
Identify and extract an API and domain type from a URL.
Identifies the type of API and domain name the input URL is using. Loops over all available API and domain profiles in the ApiManager checks against extracted url parts from
urlparse
.- Parameters
url (str) – The full url string
- Returns
tuple – The identified API profile and domain name
- Raises
ValueError – when the url does not start with http
- list_apis() list [source]¶
List the available SDSS APIs
Displays the complete list of available SDSS APIs.
- Returns
list – The list of available SDSS APIs
- list_domains() list [source]¶
List the available SDSS domains
Displays the complete list of available SDSS domain names.
- Returns
list – The list of available SDSS domains
- class sdss_brain.api.manager.ApiProfile(name: str, domain: Optional[str] = None, port: Optional[int] = None, ngrokid: Optional[int] = None, release: Optional[str] = None, test: Optional[bool] = None)[source]¶
Bases:
object
Class representing an API profile
This class provides an interface for a given SDSS API profile. It provides convenience methods for easily switching domain hosts for a given API, switching between production and development paths, and constructing full url route paths. It uses the
urlparse
URL scheme, “scheme://netloc/path;parameters?query#fragment”.- Parameters
name (str) – The name of the API profile
domain (str, optional) – The name of the domain to use, by default None
port (int, optional) – The port used for localhost domains, by default None
ngrokid (int, optional) – The ngrok id used for localhost domains, by default None
test (bool, optional) – If True, use the development url, by default None
- Variables
description (str) – A description of the API
documentation (str) – A url link to any documentation of the API
auth_type (str) – The type of authentication needed for the API
domains (dict) – The available domains this API can be accessed on
mirrors (dict) – The available domains acting as mirrors
url (str) – The current constructed base API url
current_domain (str) – The current domain the API it set to use
name (str) – The name of the API profile
token (str) – The authenticated token, if any
info (dict) – A dictionary of information extracted from Pydantic datamodel
- Raises
ValueError – when input name does not match a valid API profile
- change_domain(domain: str, port: int = None, ngrokid: int = None) None [source]¶
Change the url domain
Updates the url “netloc” segment to use the domain name provided. If the domain is “local”, also needs either a port number or ngrok id to fully construct a local domain name.
- Parameters
Example
>>> p = ApiProfile('marvin') >>> p.url 'https://sas.sdss.org/marvin/api' >>> p.change_domains('dr15') >>> p.url 'https://dr15.sdss.org/marvin/api'
- change_path(test: Optional[bool] = None, public: Optional[bool] = None) None [source]¶
Change the url path
Updates the url “path” segment. Called without arguments, with update the path to the production base. If either “test” or “public” is set will update the path with the corresponding stems, used to switch to development urls.
- Parameters
Example
>>> p = ApiProfile('marvin') >>> p.url 'https://sas.sdss.org/marvin/api' >>> p.change_path(test=True) >>> p.url 'https://sas.sdss.org/test/marvin/api'
- construct_route(route: str) str [source]¶
Construct a full url to an input route
Constructs a full url path to the input route.
- Parameters
route (str) – The route component url path
- Returns
str – The full route url
Example
>>> p = ApiProfile('marvin') >>> p.url 'https://sas.sdss.org/marvin/api' >>> p.construct_route('general/getroutemap') 'https://sas.sdss.org/marvin/api/general/getroutemap'
- construct_url(test: Optional[bool] = None, public: Optional[bool] = None) str [source]¶
Constructs a new base url
Constructs a new url given the currently set domain name and the API base name. Can optionally specify a development base using the test or public keywords.
- get_token(user: str) str [source]¶
Request and receive a valid API auth token
Requests an auth token for the specified user. This uses found netrc authentication to attempt to request and retrieve a valid token. The token should be saved in an “XXX_API_TOKEN” environment variable or in the custom sdss_brain.yml configuration file as “xxx_api_token”, where “XXX” is the API profile name.
- Parameters
user (str) – The name of the SDSS user
- Returns
str – A valid API auth token
- Raises
BrainError – when the user is not netrc validated
BrainError – when a token cannot be extracted from the http response
- class sdss_brain.api.manager.ApiProfileModel(*, domains: List[str], base: str, mirrors: List[str] = None, stems: Dict[str, str] = {'affix': 'prefix', 'public': 'public', 'test': 'test'}, api: bool = False, routemap: str = None, auth: Dict[str, str] = {'route': None, 'type': 'netrc'}, description: str = '', docs: str = None)[source]¶
Bases:
BaseModel
Pydantic class handling validation for SDSS API profiles
- class sdss_brain.api.manager.Domain(*, name: str, public: bool = False, description: str = None)[source]¶
Bases:
BaseModel
Pydantic class handling validation for SDSS domains
- sdss_brain.api.io.send_post_request(url: str, data: Optional[dict] = None) dict [source]¶
A simple httpx post request
A simple standalone httpx post request to a specified url, and given an optional data payload.
- Parameters
- Returns
dict – Extracted response data from response.json()
- Raises
BrainError – when an error occurs sending the request
Auth¶
- class sdss_brain.auth.netrc.Netrc(path: Optional[str] = None)[source]¶
Bases:
object
Class representing a netrc file
This class represents a local .netrc file, used for authenticating users against remote machines. This class validates a netrc file for existence and correct permissions. It also checks its hosts against the allowed SDSS host domains data.sdss.org and api.sdss.org and ensures their presence.
- Parameters
path (str) – The path to a .netrc file. Defaults to custom “netrc_path” config path or ~/.netrc
- check_host(host: str) bool [source]¶
Checks the host against the local netrc file
Checks if the host is a valid machine in the netrc file
- Parameters
host (str) – The netrc machine name
- Returns
bool – True if the host is valid
- read_netrc(host: str) tuple [source]¶
Read the netrc file for a given host
Reads the username, password for the given host machine. Note this returns plaintext username and password. Do not write out these values some place transparent and publicly visible.
- Parameters
host (str) – The netrc machine name
- Returns
tuple – Plain text netrc username, password
- Raises
BrainError – when netrc file fails to pass checks
ValueError – when input host is not valid
- class sdss_brain.auth.htpass.Htpass(path: Optional[str] = None)[source]¶
Bases:
object
Class representing a htpasswd file
This class represents a local .htpasswd file, used for authenticating users against the Apache password file used for HTTP Basic Authentication. This class validates a htpasswd file for existence. It allows one to list the user entries found in a local htpasswd file, as well as validate a user against the htpasswd file.
- Parameters
path (str) – The path to a .htpasswd file. Defaults to custom “htpass_path” config path or ~/.htpasswd
- list_users() list [source]¶
Return a list of users in the htpasswd file
- Returns
list – list of users in the htpasswd file
- class sdss_brain.auth.user.User(user: str)[source]¶
Bases:
object
Class representing a valid user
This class represents a valid SDSS user. It checks and validates the user against a local netrc file, a local htpasswd file, and against the SDSS collaboration.Credentials.
- Parameters
user (str) – the SDSS username
- Variables
- validate_user(password: Optional[str] = None) None [source]¶
Validate the given user
Validates the given user for netrc, htpass, and SDSS Credential authentication. Attempts to extract a valid password from the netrc file for the given user. Otherwise a password must be explicitly input.
- Parameters
password (str, optional) – The password for the given user, by default None
- Raises
ValueError – when the netrc username does not match the input user
ValueError – when no valid password is input nor extracted from the netrc
Config¶
Core¶
Mixins¶
Helpers¶
Tools¶
Exceptions¶
- exception sdss_brain.exceptions.BrainAPIError(message=None)[source]¶
Bases:
BrainError
A custom exception for API errors
- exception sdss_brain.exceptions.BrainApiAuthError(message=None)[source]¶
Bases:
BrainAPIError
A custom exception for API authentication errors
- exception sdss_brain.exceptions.BrainDeprecationWarning[source]¶
Bases:
BrainUserWarning
A warning for deprecated features.
- exception sdss_brain.exceptions.BrainError(message=None)[source]¶
Bases:
Exception
A custom core Brain exception
- exception sdss_brain.exceptions.BrainMissingDependency(message=None)[source]¶
Bases:
BrainError
A custom exception for missing dependencies.
- exception sdss_brain.exceptions.BrainNotImplemented(message=None)[source]¶
Bases:
BrainError
A custom exception for not yet implemented features.
- exception sdss_brain.exceptions.BrainSkippedTestWarning[source]¶
Bases:
BrainUserWarning
A warning for when a test is skipped.
- exception sdss_brain.exceptions.BrainUserWarning[source]¶
Bases:
UserWarning
,BrainWarning
The primary warning class.