nyx_client ========== .. py:module:: nyx_client .. autoapi-nested-parse:: NYC client SDK. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/nyx_client/circles/index /autoapi/nyx_client/client/index /autoapi/nyx_client/configuration/index /autoapi/nyx_client/connection/index /autoapi/nyx_client/data/index /autoapi/nyx_client/property/index Classes ------- .. autoapisummary:: nyx_client.Circle nyx_client.RemoteHost nyx_client.NyxClient nyx_client.SparqlResultType nyx_client.BaseNyxConfig nyx_client.ConfigType nyx_client.NyxConfigExtended nyx_client.Connection nyx_client.Data nyx_client.Property Package Contents ---------------- .. py:class:: Circle Represents a circle, which is a grouping of remote hosts. .. py:attribute:: name :type: str The name of the circle, this must be unique within your instance. .. py:attribute:: description :type: str | None :value: None Optional description of what the circle is. .. py:attribute:: did :type: str | None :value: None The did of the circle. .. py:attribute:: organizations :type: Sequence[RemoteHost] :value: () Optional list of remote organizations in the circle. .. py:method:: from_dict(value) :classmethod: Builds a circle object from json. :param value: a dictionary of the circle object :returns: Circle object .. py:method:: as_dict() Returns the object as a dictionary. :returns: A dictionary of the circle, that matches POST/PUT requests in the API. .. py:class:: RemoteHost Represents a remote host on the network. .. py:attribute:: did :type: str the name of the organization .. py:attribute:: name :type: str :value: '' the name of the organization .. py:method:: from_dict(value) :classmethod: Builds a Remote Host object from json. :param value: a dictionary of the organization object :returns: `RemoteHost` object .. py:class:: NyxClient(config = None) A client for interacting with the Nyx system. This client provides methods for querying and processing data from Nyx. .. py:attribute:: config :type: nyx_client.configuration.BaseNyxConfig Configuration for the Nyx client. .. py:attribute:: org :type: str Your organization name on Nyx. .. py:attribute:: name :type: str Your Nyx Username. .. py:attribute:: community_mode :type: bool If you're using community mode. .. py:method:: sparql_query(query, result_type = SparqlResultType.SPARQL_JSON, local_only = False) Execute a SPARQL query and process the results. NOTE: This method is experimental and its definition might change without notice! :param query: A SPARQL 1.1 query string. :param result_type: The result format for the query. :param local_only: Whether to only query the local Nyx instance as opposed to the whole Nyx network. :returns: A string of the result in the specified format :raises requests.HTTPError: If there's an HTTP error during the query execution. .. py:method:: categories() Retrieve all categories from the federated network. :returns: A list of category names. .. py:method:: genres() Retrieve all genres from the federated network. :returns: A list of genre names. .. py:method:: creators() Retrieve all creators from the federated network. :returns: A list of creator names. .. py:method:: content_types() Retrieve all content Types from the federated network. :returns: A list of content types. .. py:method:: licenses() Retrieve all licenses from the federated network. :returns: A list of licenses. .. py:method:: search(text, *, categories = (), genre = None, creator = None, license = None, content_type = None, subscription_state = 'all', timeout = 3, local_only = False) Find products using text in the Nyx network (or local instance). Usage of this endpoint is discouraged. Use :func:`get_data` instead, unless you want to perform a text search. :param text: Text to search for. :param categories: Sequence of categories to filter by. :param genre: Genre to filter by. :param creator: Creator to filter by. :param license: License to filter by. :param content_type: Content type to filter by. :param subscription_state: Subscription state to filter by. :param timeout: Timeout for the search request in seconds. :param local_only: Whether to only search for data defined in the local Nyx instance as opposed to the whole Nyx network. :returns: A list of `Data` instances matching the search criteria. .. py:method:: my_subscriptions(*, categories = (), genre = None, creator = None, license = None, content_type = None) Retrieve only subscribed data from the federated network. :param categories: Sequence of categories to filter by. :param genre: Genre to filter by. :param creator: Creator to filter by. :param license: License to filter by. :param content_type: Content type to filter by. :returns: A list of `Data` instances matching the criteria. .. py:method:: my_data(categories = (), genre = None, license = None, content_type = None) Retrieve data I have created. :param categories: Sequence of categories to filter by. :param genre: Genre to filter by. :param license: License to filter by. :param content_type: Content type to filter by. :returns: A list of `Data` instances matching the criteria. .. py:method:: get_data(*, categories = (), genre = None, creator = None, license = None, content_type = None, subscription_state = 'all', local_only = False) Find products in the Nyx network (or local instance). :param categories: Sequence of categories to filter by. :param genre: Genre to filter by. :param creator: Creator to filter by. :param license: License to filter by. :param content_type: Content type to filter by. :param subscription_state: Subscription state to filter by. :param local_only: Whether to only interrogate data defined in the local Nyx instance as opposed to the whole Nyx network. :returns: A list of `Data` instances matching the criteria. .. py:method:: get_my_data_by_name(name) Retrieve your own data based on its unique name. This only works on data you own :param name: The data unique name (unique per organization). :returns: Your `Data` instance identified with the provided name. :raises requests.HTTPError: If the API request fails. .. py:method:: create_data(name, title, description, genre, categories, content_type, lang = 'en', status = 'published', preview = '', size = None, price = None, license_url = None, download_url = None, file = None, access_control = None, circles = (), custom_metadata = (), connection_id = None) Create new data in the system. :param name: The unique identifier for the data. :param title: The display title of the data. :param description: A detailed description of the data. :param size: Approximate size of the data, if a file is provided the size will be calculated :param genre: The genre or category of the data. :param categories: A list of categories the data belongs to. :param download_url: The URL where the data can be downloaded. :param file: the file like object (RawIOBase) that you wish to upload :param content_type: The mime type of the data located at download_url. :param lang: The language of the data. :param status: The publication status of the data. :param preview: A preview or sample of the data. :param price: The price of the data in cents. If 0, the data is free. :param license_url: The URL of the license for the data. :param access_control: Either allow all, or allow none :param circles: A list of circles to add share the data with :param custom_metadata: Additional metadata properties to decorate the data with. Note that nyx-internal properties are not allowed. :param connection_id: the id of a connection to use (id from :class:`nyx_client.connection.Connection`) :returns: A `Data` instance, containing the download URL and title. :raises requests.HTTPError: If the API request fails. :raises ValueError: When download_url and file are both provided or both missing .. py:method:: update_data(name, title, description, genre, categories, content_type, lang = 'en', status = 'published', preview = '', size = None, price = None, license_url = None, download_url = None, file = None, access_control = None, circles = (), custom_metadata = (), connection_id = None) Updates existing data in the system. :param name: The unique identifier for the data. :param title: The display title of the data. :param description: A detailed description of the data. :param size: Approximate size of the data, if a file is provided the size will be calculated :param genre: The genre or category of the data. :param categories: A list of categories the data belongs to. :param download_url: The URL where the data can be downloaded. :param file: the file like object (RawIOBase) that you wish to upload :param content_type: The mime type of the data located at download_url. :param lang: The language of the data. :param status: The publication status of the data. :param preview: A preview or sample of the data. :param price: The price of the data in cents. If 0, the data is free. :param license_url: The URL of the license for the data. :param access_control: Either allow all, or allow none :param circles: A list of circles to add share the data with :param custom_metadata: Additional metadata properties to decorate the data with. Note that nyx-internal properties are not allowed. :param connection_id: the id of a connection to use :returns: A `Data` instance, containing the updated information. :raises requests.HTTPError: If the API request fails. :raises ValueError: When download_url and file are both provided or both missing .. py:method:: delete_data(data) Delete the provided data from Nyx. :param data: The data to delete. :raises requests.HTTPError: If the API request fails. .. py:method:: delete_data_by_name(name) Delete the data uniquely identified by the provided name from Nyx. :param name: The data unique name. :raises requests.HTTPError: If the API request fails. .. py:method:: subscribe(data) Subscribe to the data. :param data: The data object to subscribe to. :raises requests.HTTPError: If the API request fails. .. py:method:: unsubscribe(data) Unsubscribe from the data. :param data: The data object to unsubscribe from. :raises requests.HTTPError: If the API request fails. .. py:method:: organizations() Get a list of all organizations in the federated network. :returns: A list of `RemoteHost` objects :raises requests.HTTPError: if the API request fails. .. py:method:: get_circles() Get a list of circles. :returns: A list of `Circle` objects :raises requests.HTTPError: if the API request fails. .. py:method:: get_circle_by_name(circle_name) Get a list of circles. :param circle_name: The name of the circle to get. :returns: A `Circle` object :raises requests.HTTPError: if the API request fails. .. py:method:: create_circle(circle) Create a circle. :param circle: The circle to be created. :returns: An updated `Circle` object :raises requests.HTTPError: If the API request fails. .. py:method:: update_circle(circle) Updates a circle, based on the cirle's name. :param circle: The circle to be updated. :raises requests.HTTPError: If the API request fails. .. py:method:: delete_circle_by_name(circle_name) Deletes a circle. :param circle_name: The name of the circle to be deleted. :raises requests.HTTPError: If the API request fails. .. py:method:: delete_circle(circle) Deletes a circle. :param circle: The circle to be deleted. :raises requests.HTTPError: If the API request fails. .. py:method:: get_connections(allow_upload = None) Lists all connections. :param allow_upload: Filter the connections by allow_upload, defaults to show all. :returns: A list of `Connection` objects :raises requests.HTTPError: if the API request fails. .. py:class:: SparqlResultType Bases: :py:obj:`str`, :py:obj:`enum.Enum` Available query result (response) types for SPARQL query. .. py:method:: __str__() Return str(self). .. py:class:: BaseNyxConfig Configuration for the Nyx client. .. py:attribute:: nyx_url :type: str The URL of the Nyx instance. .. py:attribute:: nyx_password :type: str The email of the Nyx user. .. py:attribute:: nyx_email :type: str The password of the Nyx user. .. py:attribute:: override_token :type: str | None :value: None Allows injection of JWT token .. py:method:: from_env(env_file = '.env', override_token = None) :classmethod: Create a BaseNyxConfig instance from environment variables. :param env_file: Relative (to the working directory) or absolute path to the environment file. :param override_token: Token to override the default authentication. :returns: A new `BaseNyxConfig` instance. :raises ValueError: If a required variable is not set in the env file or the file does not exist. .. py:method:: __str__() Return a string representation of the configuration. :returns: A JSON string of the configuration. .. py:property:: nyx_auth :type: dict Get the authentication credentials. :returns: A dictionary containing email and password for authentication. .. py:class:: ConfigType Bases: :py:obj:`str`, :py:obj:`enum.Enum` Nyx configuration types. .. py:class:: NyxConfigExtended Extended configuration for Nyx client with API integration. .. py:attribute:: api_key :type: str The API key for the selected provider. .. py:attribute:: provider :type: ConfigType The type of configuration provider. .. py:attribute:: base_config :type: BaseNyxConfig The base Nyx configuration. .. py:method:: from_env(provider, env_file = '.env', override_token = None) :classmethod: Create a NyxConfigExtended instance from environment variables. :param provider: The type of configuration provider. :param env_file: Relative (to the working directory) or absolute path to the environment file. :param override_token: Token to override the default authentication. :returns: A new `NyxConfigExtended` instance. :raises ValueError: If a required variable is not set in the env file, the env file does not exist or the corresponding `api_key` env var is not set. .. py:class:: Connection Represents a connection to a 3rd party data integration. .. py:attribute:: id :type: str the id of the connection .. py:attribute:: name :type: str the name of the connection .. py:attribute:: json_blob :type: dict[str, Any] json blob of non sensitive storage config .. py:attribute:: description :type: str :value: '' the description of the connection .. py:attribute:: allow_update :type: bool :value: False boolean to denote if upload is allowed from this connection .. py:method:: from_dict(value) :classmethod: Builds a connection object from json. :param value: a dictionary of the connection object :returns: `Connection` object .. py:class:: Data(name, title, description, org, url, content_type, creator, categories, genre, size = 0, custom_metadata = (), connection_id = None) Represents the data in the Nyx system. This class encapsulates the information and functionality related to the data in the Nyx system, including its metadata and content retrieval. .. py:attribute:: name :type: str Unique name of data. .. py:attribute:: title :type: str Human readable title of data. .. py:attribute:: description :type: str Short description of data. .. py:attribute:: org :type: str Your organization name. .. py:attribute:: url :type: str The access URL of the data. .. py:attribute:: content_type :type: str Content type of the data, can be in format application/json, or URI. .. py:attribute:: creator :type: str Org name that created the data. .. py:attribute:: categories :type: list[str] The categories of the data. .. py:attribute:: genre :type: str The genre of the data. .. py:attribute:: size :type: int Size in bytes of the data. .. py:attribute:: custom_metadata :type: list[nyx_client.property.Property] Additional metadata properties to decorate the data with. Note that nyx-internal properties are not allowed. .. py:attribute:: connection_id :type: str | None The ID of the connection (id from :class:`nyx_client.connection.Connection`) .. py:method:: __str__() Return a string representation of the Data instance. .. py:method:: as_string() Download the content of the data as a string. This method attempts to download the content from the data's URL. :returns: The downloaded content as decoded text or None, if the download fails. .. py:method:: as_bytes() Download the content of the data as bytes. This method attempts to download the content from the data's URL. :returns: The downloaded content as bytes or None, if the download fails. .. py:class:: Property A metadata property with a single value. Multiple instances are used to represent a key (predicate) with multiple values. .. py:attribute:: key :type: str The key (predicate) of the property. Must be an IRI. .. py:attribute:: value :type: PropertyValue The value (object) of the property. One of :class:`LangLiteral`, :class:`StringLiteral`, :class:`Literal` or :class:`Uri` .. py:method:: as_dict() Returns the object as a dictionary. :returns: A dictionary of the Property that matches layout expected by the API. .. py:method:: from_dict(data) :classmethod: Returns a new property instance constructed from the given dictionary. This is expected to be in the same format as generated by :meth:`as_dict()` (or returned nu the API). .. py:method:: lang_string(key, value, lang) :classmethod: Shorthand for creating a language-specific string property. See :class:`LangLiteral` for more details. .. py:method:: string(key, value) :classmethod: Shorthand for creating a string property (without language). See :class:`StringLiteral` for more details. .. py:method:: literal(key, value, data_type) :classmethod: Shorthand for creating a property with a specific data type. See :class:`Literal` for more details. .. py:method:: uri(key, uri) :classmethod: Shorthand for creating a URI property. See :class:`Uri` for more details.