API Reference

Auto-generated from the package docstrings.

Clients

A compact, robust HTTP client for the Wisefood Data API.

class wisefood.client.Credentials(username=None, password=None, client_id=None, client_secret=None)[source]

Bases: object

Either user credentials (username & password) OR client credentials (client_id & client_secret) must be provided. They are mutually exclusive.

Parameters:

  • username (str | None)

  • password (str | None)

  • client_id (str | None)

  • client_secret (str | None)

client_id: str | None = None
client_secret: str | None = None
property is_client_credentials: bool
property is_user_credentials: bool
password: str | None = None
username: str | None = None
class wisefood.client.DataClient(base_url, credentials, *, api_prefix='/api/v1', verify_tls=True, default_timeout=30.0, pool_connections=3, pool_maxsize=3)[source]

Bases: object

HTTP client for the Wisefood Data API with automatic authentication and resource proxies.

This client handles all communication with the Wisefood Data API, providing: - Automatic authentication using username/password or client credentials - Token refresh when expired - Connection pooling and retry logic - Clean endpoint URL construction - Resource-specific proxies (articles, artifacts, guides, guidelines, textbooks, textbook passages, fctables) for convenient data access

Parameters:

  • base_url (str) – Base URL of the Wisefood Data API (e.g., ‘https://data.wisefood.com’)

  • credentials (Credentials) – Credentials object containing either username/password or client_id/client_secret

  • api_prefix (str) – API version prefix (default: ‘/api/v1’)

  • verify_tls (bool) – Whether to verify SSL/TLS certificates (default: True)

  • default_timeout (float) – Default request timeout in seconds (default: 30.0)

  • pool_connections (int) – Number of connection pools to cache (default: 3)

  • pool_maxsize (int) – Maximum number of connections to save in the pool (default: 3)

articles

ArticlesProxy for accessing scientific articles

artifacts

ArtifactsProxy for accessing artifact files and metadata

guides

GuidesProxy for accessing dietary guides

guidelines

GuidelinesProxy for accessing extracted guide rules

textbooks

TextbooksProxy for accessing textbooks

textbook_passages

TextbookPassagesProxy for accessing extracted textbook passages

fctables

FCTablesProxy for accessing food composition tables

Example

>>> creds = Credentials(username='user@example.com', password='secret')
>>> client = DataClient('https://data.wisefood.com', creds)
>>> # Access resources through proxies
>>> article = client.articles.get(123)
>>> # Or make direct API calls
>>> response = client.GET('articles', 'search', q='nutrition')
DELETE(*parts, **params)[source]

Convenient DELETE request with path parts as separate arguments.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • **params – Query parameters as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.DELETE('articles', '123')
# Equivalent to: DELETE /api/v1/articles/123
GET(*parts, **params)[source]

Convenient GET request with path parts as separate arguments.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • **params – Query parameters as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.GET('articles', 'search', q='nutrition', limit=10)
# Equivalent to: GET /api/v1/articles/search?q=nutrition&limit=10
PATCH(*parts, params=None, **json)[source]

Convenient PATCH request with path parts and JSON body.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • params – Optional query parameters

  • **json – JSON body fields as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.PATCH('articles', '123', status='published')
# Equivalent to: PATCH /api/v1/articles/123 with JSON body
POST(*parts, params=None, **json)[source]

Convenient POST request with path parts and JSON body.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • params – Optional query parameters

  • **json – JSON body fields as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.POST('articles', title='Study', doi='10.1234/example')
# Equivalent to: POST /api/v1/articles with JSON body
PUT(*parts, params=None, **json)[source]

Convenient PUT request with path parts and JSON body.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • params – Optional query parameters

  • **json – JSON body fields as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.PUT('articles', '123', title='Updated Study')
# Equivalent to: PUT /api/v1/articles/123 with JSON body
property api_base: str

Get the full API base URL combining base_url and api_prefix.

Returns:

//data.wisefood.com/api/v1’)

Return type:

Complete API base URL (e.g., ‘https

authenticate()[source]

Authenticate with the API and store bearer token with expiry timestamp.

Uses either username/password (user credentials) or client_id/client_secret (machine-to-machine credentials) depending on the credentials type.

The token is stored internally with an automatic safety margin before expiry to ensure requests don’t fail due to token expiration.

Raises:

WisefoodError – If authentication fails or response is invalid

Return type:

None

delete(endpoint, **kwargs)[source]

Perform a DELETE request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **kwargs (Any) – Request arguments (typically params for query parameters)

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.delete('articles/123')
endpoint(endpoint)[source]

Construct absolute URL for an API endpoint.

Parameters:

endpoint (str) – Relative endpoint path (e.g., ‘articles/123’ or ‘/articles/123’)

Returns:

//data.wisefood.com/api/v1/articles/123’)

Return type:

Complete URL (e.g., ‘https

get(endpoint, **params)[source]

Perform a GET request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **params (Any) – Query parameters as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.get('articles/search', q='nutrition', limit=10)
patch(endpoint, **kwargs)[source]

Perform a PATCH request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **kwargs (Any) – Request arguments (typically json=dict or data=dict)

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.patch('articles/123', json={'status': 'published'})
ping()[source]

Check authentication status and get user/client information.

Returns:

Dictionary containing authentication status and user/client details

Return type:

Dict[str, Any]

Example

>>> status = client.ping()
>>> print(status.get('username'))
post(endpoint, **kwargs)[source]

Perform a POST request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **kwargs (Any) – Request arguments (typically json=dict or data=dict)

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.post('articles', json={'title': 'Study', 'doi': '10.1234/example'})
put(endpoint, **kwargs)[source]

Perform a PUT request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **kwargs (Any) – Request arguments (typically json=dict or data=dict)

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.put('articles/123', json={'title': 'Updated Study'})
request(method, endpoint, *, auth=True, timeout=None, headers=None, params=None, **kwargs)[source]

Low-level HTTP request method with automatic authentication.

Parameters:

  • method (str) – HTTP method (GET, POST, PUT, PATCH, DELETE)

  • endpoint (str) – API endpoint path relative to api_base

  • auth – Whether to include authentication token (default: True)

  • timeout – Request timeout in seconds (uses default_timeout if None)

  • headers – Additional HTTP headers to include

  • params – Query parameters for the request

  • **kwargs – Additional arguments passed to requests (e.g., json, data)

Returns:

requests.Response object

Raises:

  • ValueError – If GET/DELETE request includes a request body

  • WisefoodError – If the API returns an error response

Example

>>> response = client.request('GET', 'articles/123')
>>> response = client.request('POST', 'articles', json={'title': 'Study'})
exception wisefood.client.WisefoodError[source]

Bases: RuntimeError

A compact, robust HTTP client for the Wisefood API (systemic operations).

class wisefood.api_client.Client(base_url, credentials, *, api_prefix='/api/v1', verify_tls=True, default_timeout=30.0, pool_connections=3, pool_maxsize=10)[source]

Bases: object

HTTP client for the Wisefood API with automatic authentication and token management.

This client handles all communication with the Wisefood API, including: - Automatic authentication using username/password or client credentials - Token refresh when expired - Connection pooling and retry logic - Clean endpoint URL construction

Parameters:

  • base_url (str) – Base URL of the Wisefood API (e.g., ‘https://api.wisefood.com’)

  • credentials (Credentials) – Credentials object containing either username/password or client_id/client_secret

  • api_prefix (str) – API version prefix (default: ‘/api/v1’)

  • verify_tls (bool) – Whether to verify SSL/TLS certificates (default: True)

  • default_timeout (float) – Default request timeout in seconds (default: 30.0)

  • pool_connections (int) – Number of connection pools to cache (default: 3)

  • pool_maxsize (int) – Maximum number of connections to save in the pool (default: 10)

Example

>>> creds = Credentials(username='user@example.com', password='secret')
>>> client = Client('https://api.wisefood.com', creds)
>>> response = client.GET('foods', 'search', q='apple')
>>> foods = response.json()
DELETE(*parts, **params)[source]

Convenient DELETE request with path parts as separate arguments.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • **params – Query parameters as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.DELETE('foods', '123')
# Equivalent to: DELETE /api/v1/foods/123
GET(*parts, **params)[source]

Convenient GET request with path parts as separate arguments.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • **params – Query parameters as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.GET('foods', 'search', q='apple', limit=10)
# Equivalent to: GET /api/v1/foods/search?q=apple&limit=10
PATCH(*parts, params=None, **json)[source]

Convenient PATCH request with path parts and JSON body.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • params – Optional query parameters

  • **json – JSON body fields as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.PATCH('foods', '123', calories=100)
# Equivalent to: PATCH /api/v1/foods/123 with JSON body
POST(*parts, params=None, **json)[source]

Convenient POST request with path parts and JSON body.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • params – Optional query parameters

  • **json – JSON body fields as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.POST('foods', name='Apple', calories=95)
# Equivalent to: POST /api/v1/foods with JSON body
PUT(*parts, params=None, **json)[source]

Convenient PUT request with path parts and JSON body.

Parameters:

  • *parts – URL path segments that will be joined with ‘/’

  • params – Optional query parameters

  • **json – JSON body fields as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.PUT('foods', '123', name='Green Apple')
# Equivalent to: PUT /api/v1/foods/123 with JSON body
property api_base: str

Get the full API base URL combining base_url and api_prefix.

Returns:

//api.wisefood.com/api/v1’)

Return type:

Complete API base URL (e.g., ‘https

authenticate()[source]

Authenticate with the API and store bearer token with expiry timestamp.

Uses either username/password (user credentials) or client_id/client_secret (machine-to-machine credentials) depending on the credentials type.

The token is stored internally with an automatic safety margin before expiry to ensure requests don’t fail due to token expiration.

Raises:

WisefoodError – If authentication fails or response is invalid

Return type:

None

delete(endpoint, **kwargs)[source]

Perform a DELETE request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **kwargs (Any) – Request arguments (typically params for query parameters)

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.delete('foods/123')
endpoint(endpoint)[source]

Construct absolute URL for an API endpoint.

Parameters:

endpoint (str) – Relative endpoint path (e.g., ‘foods/123’ or ‘/foods/123’)

Returns:

//api.wisefood.com/api/v1/foods/123’)

Return type:

Complete URL (e.g., ‘https

get(endpoint, **params)[source]

Perform a GET request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **params (Any) – Query parameters as keyword arguments

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.get('foods/search', q='apple', limit=10)
patch(endpoint, **kwargs)[source]

Perform a PATCH request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **kwargs (Any) – Request arguments (typically json=dict or data=dict)

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.patch('foods/123', json={'calories': 100})
ping()[source]

Check authentication status and get user/client information.

Returns:

Dictionary containing authentication status and user/client details

Return type:

Dict[str, Any]

Example

>>> status = client.ping()
>>> print(status.get('username'))
post(endpoint, **kwargs)[source]

Perform a POST request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **kwargs (Any) – Request arguments (typically json=dict or data=dict)

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.post('foods', json={'name': 'Apple', 'calories': 95})
put(endpoint, **kwargs)[source]

Perform a PUT request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path

  • **kwargs (Any) – Request arguments (typically json=dict or data=dict)

Returns:

requests.Response object

Return type:

Response

Example

>>> response = client.put('foods/123', json={'name': 'Green Apple'})
request(method, endpoint, *, auth=True, timeout=None, headers=None, params=None, **kwargs)[source]

Low-level HTTP request method with automatic authentication.

Parameters:

  • method (str) – HTTP method (GET, POST, PUT, PATCH, DELETE)

  • endpoint (str) – API endpoint path relative to api_base

  • auth – Whether to include authentication token (default: True)

  • timeout – Request timeout in seconds (uses default_timeout if None)

  • headers – Additional HTTP headers to include

  • params – Query parameters for the request

  • **kwargs – Additional arguments passed to requests (e.g., json, data)

Returns:

requests.Response object

Raises:

Example

>>> response = client.request('GET', 'foods/123')
>>> response = client.request('POST', 'foods', json={'name': 'Apple'})
class wisefood.api_client.Credentials(username=None, password=None, client_id=None, client_secret=None)[source]

Bases: object

Either user credentials (username & password) OR client credentials (client_id & client_secret) must be provided. They are mutually exclusive.

Parameters:

  • username (str | None)

  • password (str | None)

  • client_id (str | None)

  • client_secret (str | None)

client_id: str | None = None
client_secret: str | None = None
property is_client_credentials: bool
property is_user_credentials: bool
password: str | None = None
username: str | None = None
exception wisefood.api_client.WisefoodError[source]

Bases: RuntimeError

Entities & Proxies

class wisefood.entities.base.BaseCollectionProxy(client)[source]

Bases: object

Indexable / sliceable view over a collection of entities.

The list endpoint is expected to return either:

  • {“result”: [“urn:…”,”urn:…”, …]}

  • {“result”: [“uuid-…”,”uuid-…”, …]}

  • {“result”: [{“urn”: “…”, …}, …]}

  • {“result”: [{“id”: “…”, …}, …]}

Parameters:

client (DataClient)

DEFAULT_PAGE_SIZE: ClassVar[int] = 100
ENDPOINT: ClassVar[str] = ''
ENTITY_CLS

alias of BaseEntity

create(*, urn=None, identifier=None, **fields)[source]

Create a new entity through the proxy and return its proxy object.

Keeps the cached index in sync when it has already been populated.

Parameters:

  • urn (str | None)

  • identifier (str | None)

  • fields (Any)

Return type:

BaseEntity

enhance(agent, *, urn=None, identifier=None, **fields)[source]

Enhance an existing entity through the proxy and return its proxy object.

Keeps the cached index in sync when it has already been populated.

Parameters:

  • agent (str)

  • urn (str | None)

  • identifier (str | None)

  • fields (Any)

Return type:

BaseEntity

get(identifier, *, lazy=False)[source]

Fetch a single entity by identifier.

Parameters:
Return type:

BaseEntity

search(q, fl=None, limit=10, offset=0, fq=None, sort=None, fields=None, facet_limit=50, highlight=False, highlight_fields=None, highlight_pre_tag='<em>', highlight_post_tag='</em>')[source]

Search entities with optional filters and highlighting.

Parameters:
Return type:

List[BaseEntity]

slugs()[source]

Return completion-friendly identifiers for all known entities.

Return type:

List[str]

class wisefood.entities.base.BaseEntity(client, data=<factory>, sync=True, _dirty_fields=<factory>)[source]

Bases: object

Lightweight proxy for a single API entity.

Subclasses must define:

  • ENDPOINT (e.g. “articles”)

  • IDENTIFIER_FIELD (e.g. “urn” or “id”)

  • URN_PREFIX / IDENTIFIER_PREFIX for URN-backed entities

Parameters:
ENDPOINT: ClassVar[str] = ''
IDENTIFIER_FIELD: ClassVar[str] = 'urn'
IDENTIFIER_PREFIX: ClassVar[str] = ''
IMMUTABLE_FIELDS: ClassVar[Set[str]] = {'created_at', 'creator', 'id', 'updated_at', 'urn'}
URN_PREFIX: ClassVar[str] = ''
property artifacts

Return a parent-bound artifacts proxy for URN-backed entities.

classmethod build_identifier(value)[source]
Parameters:

value (str)

Return type:

str

client: DataClient
classmethod create(client, *, urn=None, identifier=None, **fields)[source]

Create a new entity and return a proxy for it.

Parameters:

  • client (DataClient)

  • urn (Optional[str])

  • identifier (Optional[str])

  • fields (Any)

Return type:

BaseEntity

data: Dict[str, Any]
delete()[source]
Return type:

None

dict()[source]

Return the full metadata payload as a dictionary.

Return type:

Dict[str, Any]

classmethod enhance(client, *, urn=None, identifier=None, agent, **fields)[source]

Enhance an existing entity and return a proxy for it.

Parameters:
Return type:

BaseEntity

enhance_self(*, agent, **fields)[source]

Enhance this entity using an AI agent and update its data.

Parameters:

  • agent (str) – The AI agent identifier to use for enhancement

  • **fields (Any) – Additional fields to send with the enhancement request

Return type:

None

classmethod get(client, identifier)[source]

Fetch a single entity by identifier and return a proxy.

Parameters:
Return type:

BaseEntity

property identifier: str
json()[source]

Pretty-print the full metadata payload.

Return type:

None

classmethod normalize_identifier(value)[source]
Parameters:

value (str)

Return type:

str

classmethod normalize_urn(urn_or_slug)[source]
Parameters:

urn_or_slug (str)

Return type:

str

refresh()[source]

Reload the entity data from the API.

Return type:

None

save(*, only_dirty=False)[source]

Persist local changes to the API using PATCH.

If only_dirty=True, only fields that have been changed via Field descriptors are sent (based on _dirty_fields).

Parameters:

only_dirty (bool)

Return type:

None

show()[source]

Pretty-print the full metadata payload via Pandas

Return type:

None

sync: bool = True
property urn: str

URN of the underlying entity.

class wisefood.entities.base.Field(key=None, *, default=None, default_factory=None, read_only=False)[source]

Bases: Generic[T]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

Parameters:

  • key (Optional[str])

  • default (Optional[T])

  • default_factory (Optional[Callable[[], T]])

  • read_only (bool)

name: str | None
class wisefood.entities.articles.Article(client, data=<factory>, sync=True, _dirty_fields=<factory>)[source]

Bases: BaseEntity

Schema for /articles entities.

All attributes here are thin accessors over self.data.

Parameters:
ENDPOINT = 'articles'
URN_PREFIX = 'urn:article:'
abstract: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

age_group: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

ai_category: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

ai_key_takeaways: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

ai_tags: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

annotation_confidence: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

authors: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

biological_model: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

category: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

citation_count: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

content: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

created_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

creator: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

description: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

doi: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

embedded_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

external_id: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

extras: Dict[str, Any]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

geographic_context: Dict[str, Any] | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

hard_exclusion_flags: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

id: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

influential_citation_count: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

key_takeaways: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

keywords: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

language: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

license: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

open_access: bool | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

organization_urn: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

population_group: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

publication_year: int | str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

reader_group: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

reference_count: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

region: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

status: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

study_type: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

tags: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

title: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

topics: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

type: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

updated_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

url: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

venue: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

class wisefood.entities.articles.ArticlesProxy(client)[source]

Bases: BaseCollectionProxy

Parameters:

client (DataClient)

ENDPOINT: ClassVar[str] = 'articles'
ENTITY_CLS

alias of Article

class wisefood.entities.guides.Guide(client, data=<factory>, sync=True, _dirty_fields=<factory>)[source]

Bases: BaseEntity

Parameters:
ENDPOINT = 'guides'
IMMUTABLE_FIELDS = {'created_at', 'creator', 'id', 'type', 'updated_at', 'urn'}
URN_PREFIX = 'urn:guide:'
applicability_end_date: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

applicability_start_date: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

applicability_status: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

artifact_records: List[Dict[str, Any]]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

audience: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

content: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

created_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

creator: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

description: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

document_type: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

evidence_basis: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

graphical_model: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

guideline_ids: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

property guidelines
id: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

identifiers: List[Dict[str, Any]]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

issuing_authority: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

language: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

legal_status: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

license: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

notes: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

organization_urn: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

property page
page_count: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

publication_date: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

publication_year: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

region: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

responsible_ministry: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

review_status: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

revision: Dict[str, Any] | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

short_title: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

status: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

tags: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

target_audiences: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

title: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

topic: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

type: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

updated_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

url: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

verifier_user_id: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

visibility: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

class wisefood.entities.guides.GuideGuidelinesProxy(client, guide_urn)[source]

Bases: GuidelinesProxy

Parameters:

guide_urn (str)

by_page(page_no)[source]
Parameters:

page_no (int)

Return type:

List[Guideline]

create(*, urn=None, identifier=None, **fields)[source]

Create a new entity through the proxy and return its proxy object.

Keeps the cached index in sync when it has already been populated.

Parameters:

  • urn (str | None)

  • identifier (str | None)

  • fields (Any)

Return type:

BaseEntity

search(q, fl=None, limit=10, offset=0, fq=None, sort=None, fields=None, facet_limit=50, highlight=False, highlight_fields=None, highlight_pre_tag='<em>', highlight_post_tag='</em>')[source]

Search entities with optional filters and highlighting.

Parameters:
Return type:

List[Guideline]

class wisefood.entities.guides.GuidePageProxy(guidelines)[source]

Bases: object

Parameters:

guidelines (GuideGuidelinesProxy)

class wisefood.entities.guides.Guideline(client, data=<factory>, sync=True, _dirty_fields=<factory>)[source]

Bases: BaseEntity

Parameters:
ENDPOINT = 'guidelines'
IDENTIFIER_FIELD = 'id'
IMMUTABLE_FIELDS = {'created_at', 'creator', 'guide_region', 'guide_urn', 'id', 'updated_at'}
action_type: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

applicability_end_date: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

applicability_start_date: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

applicability_status: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

created_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

creator: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

food_groups: List[Any]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

frequency: Any | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

guide_region: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

guide_urn: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

id: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

notes: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

page_no: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

quantity: Dict[str, Any] | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

review_status: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

rule_text: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

sequence_no: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

source_refs: List[Dict[str, Any]]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

status: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

target_populations: List[Any]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

title: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

updated_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

verifier_user_id: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

visibility: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

class wisefood.entities.guides.GuidelinesProxy(client)[source]

Bases: BaseCollectionProxy

Parameters:

client (DataClient)

ENDPOINT: ClassVar[str] = 'guidelines'
ENTITY_CLS

alias of Guideline

class wisefood.entities.guides.GuidesProxy(client)[source]

Bases: BaseCollectionProxy

Parameters:

client (DataClient)

ENDPOINT: ClassVar[str] = 'guides'
ENTITY_CLS

alias of Guide

class wisefood.entities.textbooks.BoundTextbookPassagesProxy(client, textbook_urn, textbook=None)[source]

Bases: TextbookPassagesProxy

Parameters:
DEFAULT_PAGE_SIZE: ClassVar[int] = 1000
bulk_replace(*, artifact_id=None, passages=None, page_count=None, structure_tree=None, extractor_name=None, extractor_run_id=None)[source]
Parameters:
Return type:

Any

by_page(page_no)[source]
Parameters:

page_no (int)

Return type:

List[TextbookPassage]

create(*, urn=None, identifier=None, **fields)[source]

Create a new entity through the proxy and return its proxy object.

Keeps the cached index in sync when it has already been populated.

Parameters:

  • urn (str | None)

  • identifier (str | None)

  • fields (Any)

Return type:

BaseEntity

search(q=None, fl=None, limit=10, offset=0, fq=None, sort=None, fields=None, facet_limit=50, highlight=False, highlight_fields=None, highlight_pre_tag='<em>', highlight_post_tag='</em>')[source]

Search entities with optional filters and highlighting.

Parameters:
Return type:

List[TextbookPassage]

class wisefood.entities.textbooks.Textbook(client, data=<factory>, sync=True, _dirty_fields=<factory>)[source]

Bases: BaseEntity

Parameters:
ENDPOINT = 'textbooks'
IMMUTABLE_FIELDS = {'created_at', 'creator', 'id', 'type', 'updated_at', 'urn'}
URN_PREFIX = 'urn:textbook:'
applicability_end_date: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

applicability_start_date: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

applicability_status: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

property artifact_record: Dict[str, Any] | None
artifact_records: List[Dict[str, Any]]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

audience: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

authors: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

created_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

creator: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

description: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

doi: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

edition: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

editors: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

id: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

isbn10: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

isbn13: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

keywords: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

language: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

license: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

organization_urn: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

property page
page_count: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

property passages
publication_date: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

publication_year: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

publisher: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

region: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

review_status: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

status: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

property structure_tree: TextbookStructureTree
structure_tree_payload: Dict[str, Any] | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

subtitle: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

tags: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

title: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

topics: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

type: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

updated_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

url: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

verifier_user_id: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

visibility: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

class wisefood.entities.textbooks.TextbookPageProxy(passages)[source]

Bases: object

Parameters:

passages (BoundTextbookPassagesProxy)

class wisefood.entities.textbooks.TextbookPassage(client, data=<factory>, sync=True, _dirty_fields=<factory>)[source]

Bases: BaseEntity

Parameters:
ENDPOINT = 'textbook-passages'
IDENTIFIER_FIELD = 'id'
IMMUTABLE_FIELDS = {'artifact_id', 'created_at', 'creator', 'id', 'structure_node_id', 'structure_path', 'textbook_urn', 'updated_at'}
artifact_id: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

char_end: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

char_start: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

created_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

creator: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

extractor_name: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

extractor_run_id: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

id: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

page_no: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

sequence_no: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

structure_node_id: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

structure_path: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

text: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

textbook_urn: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

updated_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

class wisefood.entities.textbooks.TextbookPassagesProxy(client)[source]

Bases: BaseCollectionProxy

Parameters:

client (DataClient)

ENDPOINT: ClassVar[str] = 'textbook-passages'
ENTITY_CLS

alias of TextbookPassage

by_textbook(textbook_urn)[source]
Parameters:

textbook_urn (str)

Return type:

BoundTextbookPassagesProxy

search(q=None, fl=None, limit=10, offset=0, fq=None, sort=None, fields=None, facet_limit=50, highlight=False, highlight_fields=None, highlight_pre_tag='<em>', highlight_post_tag='</em>')[source]

Search entities with optional filters and highlighting.

Parameters:
Return type:

List[BaseEntity]

class wisefood.entities.textbooks.TextbookStructureNode(textbook, payload)[source]

Bases: object

Parameters:
add_chapter(*, id, title, page_start=None, page_end=None, artifact_id=None, children=None, **fields)[source]
Parameters:
Return type:

TextbookStructureNode

add_child(*, id, title, kind, page_start=None, page_end=None, artifact_id=None, children=None, **fields)[source]
Parameters:
Return type:

TextbookStructureNode

add_section(*, id, title, page_start=None, page_end=None, artifact_id=None, children=None, **fields)[source]
Parameters:
Return type:

TextbookStructureNode

property artifact_id: str | None
property children: List[TextbookStructureNode]
dict()[source]
Return type:

Dict[str, Any]

find(node_id)[source]
Parameters:

node_id (str)

Return type:

TextbookStructureNode | None

property id: str | None
property kind: str | None
property page_end: int | None
property page_start: int | None
set(**fields)[source]
Parameters:

fields (Any)

Return type:

TextbookStructureNode

property title: str | None
to_dict()[source]
Return type:

Dict[str, Any]

class wisefood.entities.textbooks.TextbookStructureTree(textbook)[source]

Bases: MutableMapping[str, Any]

Parameters:

textbook (Textbook)

add_chapter(*, id, title, page_start=None, page_end=None, artifact_id=None, children=None, **fields)[source]
Parameters:
Return type:

TextbookStructureNode

add_root(*, id, title, kind, page_start=None, page_end=None, artifact_id=None, children=None, **fields)[source]
Parameters:
Return type:

TextbookStructureNode

clear() → None.  Remove all items from D.[source]
Return type:

None

dict()[source]
Return type:

Dict[str, Any]

find(node_id)[source]
Parameters:

node_id (str)

Return type:

TextbookStructureNode | None

property root: TextbookStructureNode
property roots: List[TextbookStructureNode]
set_root(*, id, title, kind, page_start=None, page_end=None, artifact_id=None, children=None, **fields)[source]
Parameters:
Return type:

TextbookStructureNode

to_dict()[source]
Return type:

Dict[str, Any]

class wisefood.entities.textbooks.TextbooksProxy(client)[source]

Bases: BaseCollectionProxy

Parameters:

client (DataClient)

ENDPOINT: ClassVar[str] = 'textbooks'
ENTITY_CLS

alias of Textbook

class wisefood.entities.artifacts.Artifact(client, data=<factory>, sync=True, _dirty_fields=<factory>)[source]

Bases: BaseEntity

Schema-backed entity for /artifacts.

Artifacts are addressed by UUIDs instead of URNs and are bound to a parent entity via parent_urn.

Parameters:
ENDPOINT = 'artifacts'
IDENTIFIER_FIELD = 'id'
IMMUTABLE_FIELDS = {'created_at', 'creator', 'id', 'parent_urn', 'type', 'updated_at'}
created_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

creator: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

description: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

download(*, stream=False, **kwargs)[source]

Download the file associated with this artifact.

Parameters:

stream (bool)

download_to(path, *, chunk_size=8192, **kwargs)[source]

Download the file associated with this artifact to a local path.

Parameters:
Return type:

Path

file_s3_url: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

file_size: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

file_type: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

file_url: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

id: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

language: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

parent_urn: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

save(*, only_dirty=False)[source]

Persist local changes.

The server-side update schema requires file_type, so we include it whenever we are sending a partial artifact update.

Parameters:

only_dirty (bool)

Return type:

None

title: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

type: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

updated_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

class wisefood.entities.artifacts.ArtifactsProxy(client)[source]

Bases: BaseCollectionProxy

Parameters:

client (DataClient)

ENDPOINT: ClassVar[str] = 'artifacts'
ENTITY_CLS

alias of Artifact

download(identifier, *, stream=False, **kwargs)[source]

Download the file associated with an artifact.

Parameters:
download_to(identifier, path, *, chunk_size=8192, **kwargs)[source]

Download an artifact to a local path.

Parameters:
Return type:

Path

upload(file, *, parent_urn, title=None, description=None, language=None)[source]

Upload a file and create an artifact in a single request.

Parameters:
Return type:

Artifact

class wisefood.entities.artifacts.ParentArtifactsProxy(client, parent_urn, *, parent_entity=None, embedded_records=None)[source]

Bases: ArtifactsProxy

Parameters:
create(*, urn=None, identifier=None, **fields)[source]

Create a new entity through the proxy and return its proxy object.

Keeps the cached index in sync when it has already been populated.

Parameters:

  • urn (str | None)

  • identifier (str | None)

upload(file, *, title=None, description=None, language=None)[source]

Upload a file and create an artifact in a single request.

Parameters:
Return type:

Artifact

class wisefood.entities.fctables.FCTable(client, data=<factory>, sync=True, _dirty_fields=<factory>)[source]

Bases: BaseEntity

Schema-backed entity for /fctables. Thin accessors over self.data. Adapted to represent a Food Composition Table (FCT).

Parameters:
ENDPOINT = 'fctables'
URN_PREFIX = 'urn:fctable:'
abstract: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

artifact_records: List[dict]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

authors: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

category: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

classification_schemes: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

compiling_institution: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

completeness_description: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

completeness_percent: float | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

content: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

created_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

creator: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

data_formats: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

database_name: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

description: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

external_id: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

id: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

language: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

license: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

max_nutrients_per_item: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

measurement_units: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

min_nutrients_per_item: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

number_of_entries: int | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

nutrient_coverage: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

organization_urn: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

reference_portions: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

region: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

standardization_schemes: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

status: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

tags: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

tasks_supported: List[str]

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

title: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

type: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

updated_at: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

url: str | None

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

venue: str

Descriptor mapping an attribute to a key in entity.data.

Example

title: str = Field(“title”, default=””)

class wisefood.entities.fctables.FCTablesProxy(client)[source]

Bases: BaseCollectionProxy

Parameters:

client (DataClient)

ENDPOINT: ClassVar[str] = 'fctables'
ENTITY_CLS

alias of FCTable

Household and HouseholdMember entities and proxies for the WiseFood API.

class wisefood.entities.households.Household(client=None, data=None)[source]

Bases: object

A household in the WiseFood system.

Example

>>> household = client.households.me()
>>> household.name = "New Family Name"  # auto-syncs
>>> members = household.members
Parameters:
add_member(name, age_group, **kwargs)[source]

Add a new member to this household.

Parameters:
Return type:

HouseholdMember

property created_at: str | None
delete()[source]

Delete this household.

Return type:

None

classmethod from_dict(data, client=None)[source]
Parameters:
Return type:

Household

property id: str
property members: List[HouseholdMember]

Get all members of this household.

property metadata: Dict[str, Any] | None
property name: str
property owner_id: str
refresh()[source]

Reload household data from the API.

Return type:

None

property region: str | None
to_dict()[source]
Return type:

Dict[str, Any]

property updated_at: str | None
class wisefood.entities.households.HouseholdMember(client=None, data=None)[source]

Bases: object

A member of a household.

Access the profile via the profile property which auto-fetches if needed.

Example

>>> member = client.members.get("member-id")
>>> member.profile.dietary_groups = ["vegan"]
Parameters:
property age_group: str
property created_at: str | None
delete()[source]

Delete this member.

Return type:

None

classmethod from_dict(data, client=None)[source]
Parameters:
Return type:

HouseholdMember

property household_id: str
property id: str
property image_url: str | None
property name: str
property profile: HouseholdMemberProfile

Get the member’s profile, fetching from API if not loaded.

Returns a profile object where setting properties auto-syncs to API.

Example

>>> member.profile.dietary_groups = ["vegetarian"]
>>> member.profile.nutritional_preferences = {"protein": 50}
refresh()[source]

Reload member data from the API.

Return type:

None

to_dict()[source]
Return type:

Dict[str, Any]

property updated_at: str | None
class wisefood.entities.households.HouseholdMemberProfile(client=None, member_id=None, data=None, sync=True)[source]

Bases: object

Profile information for a household member.

Setting properties automatically syncs to the API when sync=True.

Example

>>> member.profile.dietary_groups = ["vegetarian", "gluten_free"]
>>> member.profile.nutritional_preferences = {"calories": 2000}
Parameters:
delete()[source]

Delete this profile from the API.

Return type:

None

classmethod from_dict(data, client=None, member_id=None)[source]
Parameters:
Return type:

HouseholdMemberProfile

refresh()[source]

Reload profile data from the API.

Return type:

None

save()[source]

Persist changes to the API.

Return type:

None

to_dict()[source]
Return type:

Dict[str, Any]

class wisefood.entities.households.HouseholdsProxy(client)[source]

Bases: object

Proxy for household operations.

Provides convenient access to household CRUD operations through the Client.

Example

>>> client.households.me()  # Get current user's household
>>> client.households.get("household-id-123")
>>> client.households.create(name="My Family")
Parameters:

client (Client)

create(name, region=None, metadata=None, members=None)[source]

Create a new household.

Parameters:

  • name (str) – Household name

  • region (str | None) – Optional region identifier

  • metadata (Dict[str, Any] | None) – Optional metadata dictionary

  • members (List[Dict[str, Any]] | None) – Optional list of initial members to create

Returns:

Created Household object

Return type:

Household

Example

>>> household = client.households.create(
...     name="My Family",
...     region="US-CA",
...     members=[{"name": "John", "age_group": "adult"}]
... )
delete(household_id)[source]

Delete a household.

Parameters:

household_id (str) – The household’s unique identifier

Return type:

None

Example

>>> client.households.delete("abc123")
get(household_id)[source]

Get a household by ID.

Parameters:

household_id (str) – The household’s unique identifier

Returns:

Household object

Return type:

Household

Example

>>> household = client.households.get("abc123")
list(limit=100, offset=0)[source]

List all households (admin only).

Parameters:

  • limit (int) – Maximum number of results (default: 100)

  • offset (int) – Number of results to skip (default: 0)

Returns:

List of Household objects

Return type:

List[Household]

Example

>>> households = client.households.list(limit=50)
me()[source]

Get the household owned by the authenticated user.

Returns:

Household object for the current user

Return type:

Household

Example

>>> household = client.households.me()
>>> print(household.name)
update(household_id, **kwargs)[source]

Update a household.

Parameters:

  • household_id (str) – The household’s unique identifier

  • **kwargs – Fields to update (name, region, metadata)

Returns:

Updated Household object

Return type:

Household

Example

>>> household = client.households.update("abc123", name="New Name")
class wisefood.entities.households.MembersProxy(client)[source]

Bases: object

Proxy for household member operations.

Provides convenient access to member CRUD operations through the Client.

Example

>>> member = client.members.get("member-id-123")
>>> member.profile.dietary_groups = ["vegetarian"]  # auto-syncs
Parameters:

client (Client)

create(household_id, name, age_group, image_url=None)[source]

Create a new household member.

Parameters:

  • household_id (str) – The household’s unique identifier

  • name (str) – Member name

  • age_group (str) – Age group (child, teen, adult, senior, etc.)

  • image_url (str | None) – Optional URL to member’s profile image

Returns:

Created HouseholdMember object

Return type:

HouseholdMember

Example

>>> member = client.members.create(
...     household_id="abc123",
...     name="John",
...     age_group="adult"
... )
>>> member.profile.dietary_groups = ["vegetarian"]
delete(member_id)[source]

Delete a household member.

Parameters:

member_id (str) – The member’s unique identifier

Return type:

None

Example

>>> client.members.delete("member123")
get(member_id)[source]

Get a household member by ID.

Parameters:

member_id (str) – The member’s unique identifier

Returns:

HouseholdMember object with auto-syncing profile

Return type:

HouseholdMember

Example

>>> member = client.members.get("member123")
>>> member.profile.dietary_groups = ["vegan"]
list(household_id, limit=100, offset=0)[source]

List household members.

Parameters:

  • household_id (str) – The household’s unique identifier

  • limit (int) – Maximum number of results (default: 100)

  • offset (int) – Number of results to skip (default: 0)

Returns:

List of HouseholdMember objects

Return type:

List[HouseholdMember]

Example

>>> members = client.members.list(household_id="abc123")

Exceptions

exception wisefood.exceptions.APIError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: Exception

Base client-side API error.

Mirrors the server-side structure:

{
  "success": false,
  "error": {
      "title": "...",
      "detail": "...",
      "code": "resource/not_found",
      ...
  },
  "help": "http://.../api/v1/articles/hello"
}
Parameters:
Return type:

None

code: str | None = None
detail: str = ''
errors: Any = None
extra: Dict[str, Any] = None
help_url: str | None = None
response_body: Any = None
property retryable: bool

Whether a retry might make sense (for client backoff logic).

status_code: int
title: str | None = None
exception wisefood.exceptions.AuthenticationError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.AuthorizationError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.BadGatewayError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.ConflictError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.DataError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.GatewayTimeoutError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.InternalError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.InvalidError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.NotAllowedError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.NotFoundError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.RateLimitError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

exception wisefood.exceptions.ServiceUnavailableError(status_code, detail='', code=None, title=None, errors=None, extra=None, help_url=None, response_body=None)[source]

Bases: APIError

Parameters:
Return type:

None

wisefood.exceptions.error_from_response(response)[source]

Build a concrete APIError subclass from a requests.Response.

Expected Wisefood error payload shape:

{
  "success": false,
  "error": {
    "title": "NotFoundError",
    "detail": "Article with URN urn:article:hello not found.",
    "code": "resource/not_found",
    ... maybe other keys ...
  },
  "help": "http://.../api/v1/articles/hello"
}

If the body is not JSON or doesn’t match the envelope, we still build a generic APIError with whatever information we can.

Return type:

APIError

wisefood.exceptions.raise_for_api_error(response)[source]

Inspect a requests.Response and raise a suitable APIError subclass if the Wisefood API indicates failure.

Usage in your client:

resp = self.get("articles/hello")
raise_for_api_error(resp)
data = resp.json()["result"]

Behavior: - If HTTP status is 2xx and success is True → returns silently. - If HTTP status >= 400 or success is False → raises APIError subclass.

Return type:

None