# CluedIn
[cluedin](https://pypi.org/project/cluedin/) is a Python client for [CluedIn](https://www.cluedin.com/) API.
## Installation
From [PyPi](https://pypi.org/project/cluedin/):
```shell
pip install cluedin
```
## Quick start
### CluedIn context configuration
Create a JSON file with context configuration to your CluedIn instance:
In this file, parameters have the following meaning:
- `protocol` - `http` if your CluedIn instance is not secured with a TLS certificate. Otherwise, `https` by default.
- `domain` – CluedIn instance domain without the Organization prefix.
- `org_name` – the name of Organization (a.k.a. Organization prefix).
- `user_email` – the user's email.
- `user_password` – the user's password.
- `verify_tls` – `false`, if an unknown CA signs the TLS certificate. Otherwise, `true` by default.
Here is an example of a file for a CluedIn instance running locally from a [Home](https://cluedin-io.github.io/Home/) repository:
```json
{
"protocol": "http",
"domain": "127.0.0.1.nip.io",
"org_name": "foobar",
"user_email": "admin@foobar.com",
"user_password": "Foobar23!"
}
```
We add the protocol, but we can skip this parameter if the URL starts with `https`. Likewise, we can skip `verify_tls` because it only makes sense for HTTPs URLs.
Alternatively, to provide email and password, you can obtain an API access token from CluedIn UI and provide it in the file:
```json
{
"protocol": "http",
"domain": "127.0.0.1.nip.io",
"org_name": "foobar",
"access_token": "..."
}
```
When the configuration file exists, you can export its path to an environment variable:
```shell
export CLUEDIN_CONTEXT=~/.cluedin/home.json
```
Now, you can load this file from your Python code and get an access token (if not already provided):
```python
import cluedin
context = Context.from_json_file(os.environ['CLUEDIN_CONTEXT'])
context.get_token()
```
You could also do it without the context file:
```python
context = {
"protocol": "http",
"domain": "127.0.0.1.nip.io",
"org_name": "foobar",
"user_email": "admin@foobar.com",
"user_password": "Foobar23!"
}
context = Context.from_dict(context)
context.get_token()
```
### GraphQL
Get entities:
```python
context = Context.from_json_file(os.environ['CLUEDIN_CONTEXT'])
context.get_token()
query = """
query searchEntities($cursor: PagingCursor, $query: String, $pageSize: Int) {
search(
query: $query,
sort: FIELDS,
cursor: $cursor,
pageSize: $pageSize
sortFields: {field: "id", direction: ASCENDING}
) {
totalResults
cursor
entries {
id
name
entityType
}
}
}
"""
variables = {
"query": "*",
"pageSize": 10_000
}
# it's important to request cursor in your GraphQL query,
# so cluedin.gql.entries would be able to request and return all pages
entities = cluedin.gql.entries(context, query, variables):
```
## API
### Environment
- `CLUEDIN_REQUEST_TIMEOUT_IN_SECONDS` - CluedIn API request timeout (in seconds). If not set, then it defaults to `300` (5 minutes).
### Context
- `cluedin.Context.from_dict(cls, context_dict: dict) -> Context` – creates a new `Context` object from a `dict`.
- `cluedin.Context.from_json_file(file_path: str) -> Context` – creates a new `Context` object from a JSON-file.
- `cluedin.Context.from_jwt(jwt: str) -> Context` – creates a new `Context` object from a JWT (JSON Web Token, a.k.a. access token or API token).
### Account
- `cluedin.account.get_users(context: Context, org_id: str = None) -> list` – returns all users for Organization.
- `cluedin.account.is_organization_available_response(context: Context, org_name: str) -> dict` – checks if a given Organization name is available. This method returns a JSON-response serialized into a `dict`.
- `cluedin.account.is_organization_available(context: Context, org_name: str) -> bool` – checks if a given Organization name is available. Returns a Boolean.
- `cluedin.account.is_user_available_response(context: Context, user_email: str, org_name: str) -> dict` – checks, if a user with a given email can be created or this email is already reserved. This method returns a JSON-response serialized into a `dict`.
- `cluedin.account.is_user_available(context: Context, user_email: str, org_name: str) -> bool` – checks, if a user with a given email can be created or this email is already reserved. This method returns a JSON-response serialized into a `dict`. Returns a Boolean.
- `cluedin.account.get_invitation_code(context: Context, email: str) -> str` – returns an invitation code for a given email.
- `cluedin.account.create_organization(context: Context, user_email: str, password: str, org_name: str, org_sub_domain: str = None, email_domain: str = None, allow_email_domain_signup: bool = True, new_account_access_key: str = None) -> dict` - creates a new Organization. This method returns a JSON-response serialized into a `dict`.
- `cluedin.account.create_user(context: Context, user_email: str, user_password: str) -> requests.models.Response` – creates a new user. This method returns `requests.models.Response`.
- `cluedin.account.create_admin_user(context: Context, user_email: str, user_password: str) -> requests.models.Response` – creates a new admin user. This method returns `requests.models.Response`.
- `cluedin.account.get_user(context: Context, user_id: str = None) -> dict` – returns a user by ID. If `user_id` is nor provided, the current user is returned. This method returns a JSON-response serialized into a `dict`.
### Entity
- `cluedin.entity.get_entity_blob(context: Context, entity_id: str) -> str` – returns an entity blob by ID.
- `cluedin.entity.get_entity_as_clue(context: Context, entity_id: str) -> str` – returns an entity as a clue by ID.
### GraphQL
- `cluedin.gql.gql(context: Context, query: str, variables: dict = None) -> dict` – sends a GraphQL request and returns a response.
- `cluedin.gql.org_gql(context: Context, query: str, variables: dict = None) -> dict` – sends a GraphQL request to Organization endpoint and returns a response.
- `cluedin.gql.entries(context: Context, query: str, variables: dict = None, flat=False) -> Generator` – returns entries from a GraphQL search query. If cursor is requested in the GraphQL query (see the example above and tests), then it proceeds to next pages to return all results. If `flat` is `True`, then it flattens the `properties` dictionary of each returned entity.
- `search(context: Context, search_query: str, page_size: int = 10_000) -> Generator` – returns entities by a search query. This method is a wrapper around `cluedin.gql.entries`.
### JSON
- `cluedin.json.dump(file: str, obj: Any) -> None` – serialize obj as a JSON formatted stream to file.
- `cluedin.json.load(file: str) -> Any` – deserialize file to a Python object.
### JWT
- `cluedin.jwt.get_jwt_payload(jwt: str) -> dict` – parses a JWT (JSON Web Token, a.k.a. access token or API token), and returns its payload serialized into a `dict`.
### Public API
- `cluedin.public.post_clue(context: Context, clue: str, content_type: str = 'application/xml') -> str` – posts a clue in XML or JSON format. This method returns an operation result as a string.
- `cluedin.public.restore_user_entities(context: Context) -> list` – if you accidentally deleted `/Infrastructure/User` entities, this method gets all users and restores entities for those who miss them.
### Rules
- `cluedin.rules.RuleScope` - an enumeration of rule scopes: `DATA_PART`, `ENTITY`, `SURVIVORSHIP`.
- `cluedin.rules.get_rules(context: Context, scope=RuleScope.DATA_PART) -> dict` – returns all rules for a given scope. This method returns a JSON-response serialized into a `dict`.
- `cluedin.rules.get_rule(context: Context, rule_id: str) -> dict` – returns a rule by ID. This method returns a JSON-response serialized into a `dict`.
#### Evaluator
- `cluedin.rules.evaluator.default_get_property_name(field: str) -> str` – returns a default property name for a given field. Used to map CluedIn Rules fields to your fields.
- `cluedin.rules.evaluator.default_get_value(field: str, obj: dict) -> Any` – returns a default value for a given field. Used to map CluedIn Rules fields to your fields.
- `cluedin.rules.Evaluator` – a class to evaluate CluedIn Rules.
- `cluedin.rules.Evaluator.evaluate(context: Context, rule: dict, obj: dict) -> bool` – evaluates a rule for an object. Returns a Boolean:
- `cluedin.rules.get_matching_objects(self, objects) -> list` – returns a list of objects that match the rule.
- `cluedin.rules.object_matches_rules(self, obj) -> bool` – returns `True` if an object matches the rule.
- `cluedin.rules.explain(self) -> str` – returns an explanation of the rule (in pandas `DataFrame.query` terms).
#### Operators
- `cluedin.rules.operators.default_get_operator(operator_id) -> Any` – returns a default operator for a given operator ID. Used to map CluedIn Rules operators to your operators.
You can add custom operations (see `test_operators.py` for examples), but the following CluedIn Rules operators are supported out of the box:
- `Is Not True`
- `Is True`
- `Begins With`
- `Between`
- `Contains`
- `Ends With`
- `Equals`
- `Exists`
- `Greater`
- `Greater or Equal`
- `In`
- `Is False`
- `Is Not Null`
- `Is Null`
- `Is True`
- `Less`
- `Less or Equal`
- `Matches pattern`
- `Not Begins With`
- `Not Between`
- `Not Contains`
- `Not Ends With`
- `Not Equal`
- `Does Not Exist`
- `Not In`
- `Does not match pattern`
### Vocabulary
- `cluedin.vocab.get_vocab_keys(context: Context) -> list` – gets all vocabulary keys.
Raw data
{
"_id": null,
"home_page": "https://github.com/romaklimenko/cluedin",
"name": "cluedin",
"maintainer": "Roman Klimenko",
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": "roman@klimenko.dk",
"keywords": "cluedin, mdm, master data management",
"author": "Roman Klimenko",
"author_email": "roman@klimenko.dk",
"download_url": "https://files.pythonhosted.org/packages/e3/c3/bbd1a1cd029fa3b5b3534b04b52129ef2d40fab0a157ea00bf03fa6e47bc/cluedin-2.6.0.tar.gz",
"platform": null,
"description": "# CluedIn\n\n[cluedin](https://pypi.org/project/cluedin/) is a Python client for [CluedIn](https://www.cluedin.com/) API.\n\n## Installation\n\nFrom [PyPi](https://pypi.org/project/cluedin/):\n\n```shell\npip install cluedin\n```\n\n## Quick start\n\n### CluedIn context configuration\n\nCreate a JSON file with context configuration to your CluedIn instance:\n\nIn this file, parameters have the following meaning:\n\n- `protocol` - `http` if your CluedIn instance is not secured with a TLS certificate. Otherwise, `https` by default.\n- `domain` \u2013 CluedIn instance domain without the Organization prefix.\n- `org_name` \u2013 the name of Organization (a.k.a. Organization prefix).\n- `user_email` \u2013 the user's email.\n- `user_password` \u2013 the user's password.\n- `verify_tls` \u2013 `false`, if an unknown CA signs the TLS certificate. Otherwise, `true` by default.\n\nHere is an example of a file for a CluedIn instance running locally from a [Home](https://cluedin-io.github.io/Home/) repository:\n\n```json\n{\n \"protocol\": \"http\",\n \"domain\": \"127.0.0.1.nip.io\",\n \"org_name\": \"foobar\",\n \"user_email\": \"admin@foobar.com\",\n \"user_password\": \"Foobar23!\"\n}\n```\n\nWe add the protocol, but we can skip this parameter if the URL starts with `https`. Likewise, we can skip `verify_tls` because it only makes sense for HTTPs URLs.\n\nAlternatively, to provide email and password, you can obtain an API access token from CluedIn UI and provide it in the file:\n\n```json\n{\n \"protocol\": \"http\",\n \"domain\": \"127.0.0.1.nip.io\",\n \"org_name\": \"foobar\",\n \"access_token\": \"...\"\n}\n```\n\nWhen the configuration file exists, you can export its path to an environment variable:\n\n```shell\nexport CLUEDIN_CONTEXT=~/.cluedin/home.json\n```\n\nNow, you can load this file from your Python code and get an access token (if not already provided):\n\n```python\nimport cluedin\n\ncontext = Context.from_json_file(os.environ['CLUEDIN_CONTEXT'])\ncontext.get_token()\n```\n\nYou could also do it without the context file:\n\n```python\ncontext = {\n \"protocol\": \"http\",\n \"domain\": \"127.0.0.1.nip.io\",\n \"org_name\": \"foobar\",\n \"user_email\": \"admin@foobar.com\",\n \"user_password\": \"Foobar23!\"\n}\n\ncontext = Context.from_dict(context)\ncontext.get_token()\n```\n\n### GraphQL\n\nGet entities:\n\n```python\ncontext = Context.from_json_file(os.environ['CLUEDIN_CONTEXT'])\ncontext.get_token()\n\nquery = \"\"\"\n query searchEntities($cursor: PagingCursor, $query: String, $pageSize: Int) {\n search(\n query: $query,\n sort: FIELDS,\n cursor: $cursor,\n pageSize: $pageSize\n sortFields: {field: \"id\", direction: ASCENDING}\n ) {\n totalResults\n cursor\n entries {\n id\n name\n entityType\n }\n }\n }\n\"\"\"\n\nvariables = {\n \"query\": \"*\",\n \"pageSize\": 10_000\n}\n\n# it's important to request cursor in your GraphQL query,\n# so cluedin.gql.entries would be able to request and return all pages\nentities = cluedin.gql.entries(context, query, variables):\n```\n\n## API\n\n### Environment\n\n- `CLUEDIN_REQUEST_TIMEOUT_IN_SECONDS` - CluedIn API request timeout (in seconds). If not set, then it defaults to `300` (5 minutes).\n\n### Context\n\n- `cluedin.Context.from_dict(cls, context_dict: dict) -> Context` \u2013 creates a new `Context` object from a `dict`.\n- `cluedin.Context.from_json_file(file_path: str) -> Context` \u2013 creates a new `Context` object from a JSON-file.\n- `cluedin.Context.from_jwt(jwt: str) -> Context` \u2013 creates a new `Context` object from a JWT (JSON Web Token, a.k.a. access token or API token).\n\n### Account\n\n- `cluedin.account.get_users(context: Context, org_id: str = None) -> list` \u2013 returns all users for Organization.\n- `cluedin.account.is_organization_available_response(context: Context, org_name: str) -> dict` \u2013 checks if a given Organization name is available. This method returns a JSON-response serialized into a `dict`.\n- `cluedin.account.is_organization_available(context: Context, org_name: str) -> bool` \u2013 checks if a given Organization name is available. Returns a Boolean.\n- `cluedin.account.is_user_available_response(context: Context, user_email: str, org_name: str) -> dict` \u2013 checks, if a user with a given email can be created or this email is already reserved. This method returns a JSON-response serialized into a `dict`.\n- `cluedin.account.is_user_available(context: Context, user_email: str, org_name: str) -> bool` \u2013 checks, if a user with a given email can be created or this email is already reserved. This method returns a JSON-response serialized into a `dict`. Returns a Boolean.\n- `cluedin.account.get_invitation_code(context: Context, email: str) -> str` \u2013 returns an invitation code for a given email.\n- `cluedin.account.create_organization(context: Context, user_email: str, password: str, org_name: str, org_sub_domain: str = None, email_domain: str = None, allow_email_domain_signup: bool = True, new_account_access_key: str = None) -> dict` - creates a new Organization. This method returns a JSON-response serialized into a `dict`.\n- `cluedin.account.create_user(context: Context, user_email: str, user_password: str) -> requests.models.Response` \u2013 creates a new user. This method returns `requests.models.Response`.\n- `cluedin.account.create_admin_user(context: Context, user_email: str, user_password: str) -> requests.models.Response` \u2013 creates a new admin user. This method returns `requests.models.Response`.\n- `cluedin.account.get_user(context: Context, user_id: str = None) -> dict` \u2013 returns a user by ID. If `user_id` is nor provided, the current user is returned. This method returns a JSON-response serialized into a `dict`.\n\n### Entity\n\n- `cluedin.entity.get_entity_blob(context: Context, entity_id: str) -> str` \u2013 returns an entity blob by ID.\n- `cluedin.entity.get_entity_as_clue(context: Context, entity_id: str) -> str` \u2013 returns an entity as a clue by ID.\n\n### GraphQL\n\n- `cluedin.gql.gql(context: Context, query: str, variables: dict = None) -> dict` \u2013 sends a GraphQL request and returns a response.\n- `cluedin.gql.org_gql(context: Context, query: str, variables: dict = None) -> dict` \u2013 sends a GraphQL request to Organization endpoint and returns a response.\n- `cluedin.gql.entries(context: Context, query: str, variables: dict = None, flat=False) -> Generator` \u2013 returns entries from a GraphQL search query. If cursor is requested in the GraphQL query (see the example above and tests), then it proceeds to next pages to return all results. If `flat` is `True`, then it flattens the `properties` dictionary of each returned entity.\n- `search(context: Context, search_query: str, page_size: int = 10_000) -> Generator` \u2013 returns entities by a search query. This method is a wrapper around `cluedin.gql.entries`.\n\n### JSON\n\n- `cluedin.json.dump(file: str, obj: Any) -> None` \u2013 serialize obj as a JSON formatted stream to file.\n- `cluedin.json.load(file: str) -> Any` \u2013 deserialize file to a Python object.\n\n### JWT\n\n- `cluedin.jwt.get_jwt_payload(jwt: str) -> dict` \u2013 parses a JWT (JSON Web Token, a.k.a. access token or API token), and returns its payload serialized into a `dict`.\n\n### Public API\n\n- `cluedin.public.post_clue(context: Context, clue: str, content_type: str = 'application/xml') -> str` \u2013 posts a clue in XML or JSON format. This method returns an operation result as a string.\n- `cluedin.public.restore_user_entities(context: Context) -> list` \u2013 if you accidentally deleted `/Infrastructure/User` entities, this method gets all users and restores entities for those who miss them.\n\n### Rules\n\n- `cluedin.rules.RuleScope` - an enumeration of rule scopes: `DATA_PART`, `ENTITY`, `SURVIVORSHIP`.\n- `cluedin.rules.get_rules(context: Context, scope=RuleScope.DATA_PART) -> dict` \u2013 returns all rules for a given scope. This method returns a JSON-response serialized into a `dict`.\n- `cluedin.rules.get_rule(context: Context, rule_id: str) -> dict` \u2013 returns a rule by ID. This method returns a JSON-response serialized into a `dict`.\n\n#### Evaluator\n\n- `cluedin.rules.evaluator.default_get_property_name(field: str) -> str` \u2013 returns a default property name for a given field. Used to map CluedIn Rules fields to your fields.\n- `cluedin.rules.evaluator.default_get_value(field: str, obj: dict) -> Any` \u2013 returns a default value for a given field. Used to map CluedIn Rules fields to your fields.\n- `cluedin.rules.Evaluator` \u2013 a class to evaluate CluedIn Rules.\n- `cluedin.rules.Evaluator.evaluate(context: Context, rule: dict, obj: dict) -> bool` \u2013 evaluates a rule for an object. Returns a Boolean:\n\n - `cluedin.rules.get_matching_objects(self, objects) -> list` \u2013 returns a list of objects that match the rule.\n - `cluedin.rules.object_matches_rules(self, obj) -> bool` \u2013 returns `True` if an object matches the rule.\n - `cluedin.rules.explain(self) -> str` \u2013 returns an explanation of the rule (in pandas `DataFrame.query` terms).\n\n#### Operators\n\n- `cluedin.rules.operators.default_get_operator(operator_id) -> Any` \u2013 returns a default operator for a given operator ID. Used to map CluedIn Rules operators to your operators.\n\nYou can add custom operations (see `test_operators.py` for examples), but the following CluedIn Rules operators are supported out of the box:\n\n- `Is Not True`\n- `Is True`\n- `Begins With`\n- `Between`\n- `Contains`\n- `Ends With`\n- `Equals`\n- `Exists`\n- `Greater`\n- `Greater or Equal`\n- `In`\n- `Is False`\n- `Is Not Null`\n- `Is Null`\n- `Is True`\n- `Less`\n- `Less or Equal`\n- `Matches pattern`\n- `Not Begins With`\n- `Not Between`\n- `Not Contains`\n- `Not Ends With`\n- `Not Equal`\n- `Does Not Exist`\n- `Not In`\n- `Does not match pattern`\n\n### Vocabulary\n\n- `cluedin.vocab.get_vocab_keys(context: Context) -> list` \u2013 gets all vocabulary keys.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client for CluedIn API.",
"version": "2.6.0",
"project_urls": {
"Homepage": "https://github.com/romaklimenko/cluedin",
"Repository": "https://github.com/romaklimenko/cluedin"
},
"split_keywords": [
"cluedin",
" mdm",
" master data management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e08d220650b3d8808fa5b7b717f1da5d1599d3a9cae56aa99ef35be91882e6e6",
"md5": "a14e92432bd956969bcd4c4c584c82d6",
"sha256": "8cb481f06b269c7c120e8e984cb9cee9a1c2efa1cb87927791fa204f075e323b"
},
"downloads": -1,
"filename": "cluedin-2.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a14e92432bd956969bcd4c4c584c82d6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 23501,
"upload_time": "2024-12-22T18:34:41",
"upload_time_iso_8601": "2024-12-22T18:34:41.754049Z",
"url": "https://files.pythonhosted.org/packages/e0/8d/220650b3d8808fa5b7b717f1da5d1599d3a9cae56aa99ef35be91882e6e6/cluedin-2.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3c3bbd1a1cd029fa3b5b3534b04b52129ef2d40fab0a157ea00bf03fa6e47bc",
"md5": "6e7af516b9e25ca84eb0f95c56e6962d",
"sha256": "944064e61a74b79e50984c9d4e084a9a18a4768fab00938e2dc7e7168d4e6095"
},
"downloads": -1,
"filename": "cluedin-2.6.0.tar.gz",
"has_sig": false,
"md5_digest": "6e7af516b9e25ca84eb0f95c56e6962d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 18604,
"upload_time": "2024-12-22T18:34:44",
"upload_time_iso_8601": "2024-12-22T18:34:44.127308Z",
"url": "https://files.pythonhosted.org/packages/e3/c3/bbd1a1cd029fa3b5b3534b04b52129ef2d40fab0a157ea00bf03fa6e47bc/cluedin-2.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-22 18:34:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "romaklimenko",
"github_project": "cluedin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cluedin"
}
JSON
