Utils

docculus.utils

Shared helper utilities.

docculus.utils.fake

Contain functions to generate fake documents.

It is designed to be used for testing and debugging purposes.

docculus.utils.fake.generate_fake_documents

generate_fake_documents(
    n: int = 5,
    seed: int | None = None,
    nb_sentences: int = 5,
) -> list[Document]

Generate synthetic LangChain Documents with Faker-generated content.

Each document gets a unique id ("doc-{i}"), a Faker-generated paragraph as its content, and metadata containing a fake author name and a single-word topic.

Note

Content is not guaranteed to be unique: Faker.paragraph() has no built-in uniqueness constraint, so with a large enough n (or a small enough nb_sentences), two documents could coincidentally receive identical text. If strict uniqueness matters for your use case, deduplicate the result or use Faker's unique proxy (e.g. fake.unique.paragraph(...), which raises once its internal pool is exhausted).

Warning

Faker.seed() seeds Faker's shared, process-wide random generator, not just the local fake instance created here. Passing seed therefore affects the reproducibility of any other Faker() instance used elsewhere in the same process after this function runs, not only calls made through this function.

Parameters:

Name	Type	Description	Default
n	int	Number of documents to generate. Must be non-negative; n=0 returns an empty list.	5
seed	int | None	Optional seed for reproducible output. If None, content differs on every call (see the Warning above about seeding's process-wide scope).	None
nb_sentences	int	Number of sentences per document's generated paragraph, passed through to Faker.paragraph(). Higher values reduce (but do not eliminate) the chance of two documents coincidentally sharing identical content.	5

Returns:

Type	Description
list[Document]	A list of n Document objects, each with a distinct id and independently generated content and metadata.

Raises:

Type	Description
ValueError	If n is negative.
RuntimeError	If the optional faker dependency is not installed.

Example

>>> from docculus.utils.fake import generate_fake_documents
>>> docs = generate_fake_documents(n=3, seed=42)
>>> len(docs)
3
>>> [doc.id for doc in docs]
['doc-0', 'doc-1', 'doc-2']
>>> docs2 = generate_fake_documents(n=3, seed=42)
>>> [doc.page_content for doc in docs] == [doc.page_content for doc in docs2]
True

docculus.utils.imports

Helpers to detect and validate optional dependencies.

docculus.utils.imports.check_faker

check_faker() -> None

Check if the faker package is installed.

Raises:

Type	Description
RuntimeError	if the faker package is not installed.

Example

>>> from docculus.utils.imports import check_faker
>>> check_faker()

docculus.utils.imports.check_persista

check_persista() -> None

Check if the persista package is installed.

Raises:

Type	Description
RuntimeError	if the persista package is not installed.

Example

>>> from docculus.utils.imports import check_persista
>>> check_persista()

docculus.utils.imports.faker_available

faker_available(fn: F) -> F

Implement a decorator to execute a function only if faker package is installed.

Parameters:

Name	Type	Description	Default
fn	F	The function to execute.	required

Returns:

Type	Description
F	A wrapper around fn. Calling the wrapper executes fn and returns its result if faker is installed, otherwise it returns None without calling fn.

Example

>>> from docculus.utils.imports import faker_available
>>> @faker_available
... def my_function(n: int = 0) -> int:
...     return 42 + n
...
>>> my_function()

docculus.utils.imports.is_faker_available cached

is_faker_available() -> bool

Indicate if the faker package is installed or not.

Returns:

Type	Description
bool	True if faker is available otherwise False.

Example

>>> from docculus.utils.imports import is_faker_available
>>> is_faker_available()

docculus.utils.imports.is_persista_available cached

is_persista_available() -> bool

Indicate if the persista package is installed or not.

Returns:

Type	Description
bool	True if persista is available otherwise False.

Example

>>> from docculus.utils.imports import is_persista_available
>>> is_persista_available()

docculus.utils.imports.persista_available

persista_available(fn: F) -> F

Implement a decorator to execute a function only if persista package is installed.

Parameters:

Name	Type	Description	Default
fn	F	The function to execute.	required

Returns:

Type	Description
F	A wrapper around fn. Calling the wrapper executes fn and returns its result if persista is installed, otherwise it returns None without calling fn.

Example

>>> from docculus.utils.imports import persista_available
>>> @persista_available
... def my_function(n: int = 0) -> int:
...     return 42 + n
...
>>> my_function()

docculus.utils.imports.raise_faker_missing_error

raise_faker_missing_error() -> NoReturn

Raise a RuntimeError to indicate the faker package is missing.

docculus.utils.imports.raise_persista_missing_error

raise_persista_missing_error() -> NoReturn

Raise a RuntimeError to indicate the persista package is missing.