LacusCore

https://lacuscore.readthedocs.io/en/latest/
Admin
LacusCore is the core module used by Lacus to enqueue, trigger, and retrieve the results of web...
Tokens:10,174
Snippets:82
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install LacusCore

Source: https://lacuscore.readthedocs.io/en/latest/index.html

Install the LacusCore package from PyPi using pip.

```bash
pip install lacuscore

```

--------------------------------

### Install LacusCore

Source: https://lacuscore.readthedocs.io/en/latest/_sources/index.rst.txt

Install the LacusCore package using pip.

```bash
pip install lacuscore
```

--------------------------------

### start_session()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Starts a new session. This method is part of the XpraSessionManager class.

```APIDOC
## start_session()

### Description
Starts a new session.

### Method
(Not specified, likely a method call within the XpraSessionManager class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### start_session

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Starts a new xpra session with a given name and dynamically allocates a display. It returns details about the running xpra process and its transport.

```APIDOC
## start_session

### Description
Starts an xpra session with the given name and allocates a display dynamically.

### Method
None

### Endpoint
None

### Parameters
#### Path Parameters
- **session_name** (str) - Unique name for the remote headed session (capture UUID).
- **ttl** (int) - Time-to-live in seconds for the remote headed session.

### Request Example
None

### Response
#### Success Response
- **tuple[XpraSession, SessionMetadata, dict[str, str]]** - A tuple containing the XpraSession describing the running xpra process, its SessionMetadata, and internal transport details.

#### Response Example
None
```

--------------------------------

### Trigger Captures from Queue

Source: https://lacuscore.readthedocs.io/en/latest/index.html

Asynchronously trigger and process captures from the queue. This example consumes up to 10 captures and waits for them to complete.

```python
import asyncio

from redis import Redis

from lacuscore import LacusCore

redis = Redis()  # Connector to a running Redis/Valkey instance
lacus = LacusCore(redis)

async def run_captures() -> None:
    max_captures_to_consume = 10
    captures = set()
    for capture_task in lacus.consume_queue(max_captures_to_consume):
        captures.add(capture_task)  # adds the task to the set
        capture_task.add_done_callback(captures.discard)  # remove the task from the set when done

    await asyncio.gather(*captures)  # wait for all tasks to complete

asyncio.run(run_captures())

```

--------------------------------

### Get Capture Result

Source: https://lacuscore.readthedocs.io/en/latest/index.html

Retrieve the result of a completed capture using its UUID.

```python
result = lacus.get_capture(uuid)

```

--------------------------------

### Get Capture Result

Source: https://lacuscore.readthedocs.io/en/latest/_sources/index.rst.txt

Retrieves the result of a completed capture using its UUID.

```python
result = lacus.get_capture(uuid)
```

--------------------------------

### get_capture_status

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Gets the current status of a capture job using its UUID.

```APIDOC
## get_capture_status

### Description
Gets the current status of a capture job using its UUID.

### Method
GET

### Endpoint
/capture/{uuid}/status

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture (given by enqueue)

### Returns
#### Success Response
- **CaptureStatus** - The status of the capture.
```

--------------------------------

### Get Capture Status

Source: https://lacuscore.readthedocs.io/en/latest/index.html

Retrieve the status of a capture using its UUID. Status codes indicate queued, done, ongoing, or unknown.

```python
status = lacus.get_capture_status(uuid)

# 0 = queued / 1 = done / 2 = ongoing / -1 = Unknown UUID

```

--------------------------------

### Get Capture Status

Source: https://lacuscore.readthedocs.io/en/latest/_sources/index.rst.txt

Retrieves the status of a capture using its UUID. Status codes indicate queued, done, ongoing, or unknown.

```python
status = lacus.get_capture_status(uuid)

# 0 = queued / 1 = done / 2 = ongoing / -1 = Unknown UUID
```

--------------------------------

### LacusCore Class Initialization

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Initializes the LacusCore class with various configuration options for capturing web content. It allows customization of Redis connection, capture timeouts, proxy settings, and browser behavior.

```APIDOC
## LacusCore Class

### Description
Initializes the LacusCore class with various configuration options for capturing web content. It allows customization of Redis connection, capture timeouts, proxy settings, and browser behavior.

### Parameters
* **redis_connector** (Redis[bytes]) - Pre-configured connector to a redis instance.
* **max_capture_time** (int) - If the capture takes more than that time, break (in seconds). Default: 3600.
* **expire_results** (int) - The capture results are stored in redis. Expire them after they are done (in seconds). Default: 36000.
* **tor_proxy** (dict[str, str] | str | None) - URL to a SOCKS5 tor proxy. If you have tor installed, this is the default: socks5://127.0.0.1:9050.
* **i2p_proxy** (dict[str, str] | str | None) - URL to a HTTP I2P proxy. If you have i2p installed, this is the default: http://127.0.0.1:4444.
* **only_global_lookups** (bool) - Discard captures that point to non-public IPs. Default: True.
* **max_retries** (int) - How many times should we re-try a capture if it failed. Default: 3.
* **headed_allowed** (bool) - Allow to launch captures in a local headed browser. Default: False.
* **remote_headed_allowed** (bool) - Allow to trigger a capture in a remote headed browser. Default: False.
* **remote_headed_backend_type** (str | None) - The backend type for the remote headed captures (curently, Xpra).
* **tt_settings** (TrustedTimestampSettings | None) - The settings for the Trusted Timestamps.
* **loglevel** (str | int) - Logging level. Default: 'INFO'.
```

--------------------------------

### Enqueue a URL for Capture

Source: https://lacuscore.readthedocs.io/en/latest/_sources/index.rst.txt

Enqueues a URL for capture using LacusCore and Redis. Requires a running Redis/Valkey instance.

```python
from redis import Redis
from lacuscore import LacusCore

redis = Redis()  # Connector to a running Redis/Valkey instance
lacus = LacusCore(redis)
uuid = lacus.enqueue(url='google.fr')
```

--------------------------------

### Enqueue a URL for Capture

Source: https://lacuscore.readthedocs.io/en/latest/index.html

Enqueue a URL for capture using LacusCore. This requires a running Redis or Valkey instance.

```python
from redis import Redis
from lacuscore import LacusCore

redis = Redis()  # Connector to a running Redis/Valkey instance
lacus = LacusCore(redis)
uuid = lacus.enqueue(url='google.fr')

```

--------------------------------

### settings()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Retrieves or sets settings. This method is part of the LacusCore class.

```APIDOC
## settings()

### Description
Retrieves or sets settings.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### settings

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves the public settings for the LacusCore instance.

```APIDOC
## settings

### Description
Retrieves the public settings for the LacusCore instance.

### Method
GET

### Endpoint
/settings

### Returns
#### Success Response
- **dict[str, str | bool | int]** - A dictionary containing the public settings.
```

--------------------------------

### settings

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves the public settings for the LacusCore instance.

```APIDOC
## settings

### Description
Gets the public settings for the instance.

### Method
GET (assumed)

### Endpoint
/settings

### Response
#### Success Response
- **dict[str, str | bool | int]** - A dictionary containing the public settings.

### Response Example
```json
{
  "setting_name": "setting_value"
}

```

--------------------------------

### LacusCore.settings()

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves the current settings. This method is part of the LacusCore class.

```APIDOC
## LacusCore.settings()

### Description
Retrieves the current settings.

### Method
[Method signature or HTTP method if applicable]

### Parameters
None

### Response
- **settings**: dict - A dictionary containing the current settings.
```

--------------------------------

### playwright_devices

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Fetches a list of devices that are exposed by Playwright.

```APIDOC
## playwright_devices

### Description
Fetches a list of devices that are exposed by Playwright.

### Method
GET

### Endpoint
/devices

### Returns
#### Success Response
- **dict[str, Any]** - A dictionary containing information about available Playwright devices.
```

--------------------------------

### enqueue()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Enqueues an item. This method is part of the LacusCore class.

```APIDOC
## enqueue()

### Description
Enqueues an item.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### enqueue

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Enqueues a capture job with specified settings. This method allows for detailed configuration of the capture process, including URL, document content, browser settings, and various advanced options.

```APIDOC
## enqueue

### Description
Enqueues a capture job with specified settings. This method allows for detailed configuration of the capture process, including URL, document content, browser settings, and various advanced options.

### Method
POST

### Endpoint
/capture

### Parameters
#### Query Parameters
- **settings** (dict) - Required - Settings as a dictionary
- **url** (str) - Optional - URL to capture (incompatible with document and document_name)
- **document_name** (str) - Optional - Filename of the document to capture (required if document is used)
- **document** (str) - Optional - Document to capture itself (requires a document_name), must be base64 encoded
- **depth** (int) - Optional - [Dangerous] Depth of the capture. If > 0, the URLs of the rendered document will be extracted and captured. It can take a very long time.
- **browser** (str) - Optional - The browser to use for the capture
- **device_name** (str) - Optional - The name of the device, must be something Playwright knows
- **user_agent** (str) - Optional - The user agent the browser will use for the capture
- **proxy** (str) - Optional - SOCKS5 proxy to use for capturing
- **socks5_dns_resolver** (str) - Optional - DNS resolver for to populate IPs in HAR when a capture is done via a socks5 proxy.
- **general_timeout_in_sec** (int) - Optional - The capture will raise a timeout if it takes more than that time
- **cookies** (list) - Optional - A list of cookies
- **storage** (any) - Optional - A storage state from another capture
- **headers** (dict) - Optional - The headers to pass to the capture
- **http_credentials** (dict) - Optional - HTTP Credentials to pass to the capture
- **geolocation** (dict) - Optional - Geolocation of the browser to pass to the capture
- **timezone_id** (str) - Optional - The timezone of the browser to pass to the capture
- **locale** (str) - Optional - The locale of the browser to pass to the capture
- **color_scheme** (str) - Optional - The prefered color scheme of the browser to pass to the capture
- **java_script_enabled** (bool) - Optional - If False, javascript will be disabled when rendering the page
- **viewport** (dict) - Optional - The viewport of the browser used for capturing
- **referer** (str) - Optional - The referer URL for the capture
- **rendered_hostname_only** (bool) - Optional - If depth > 0: only capture URLs with the same hostname as the rendered page
- **with_screenshot** (bool) - Optional - If False, PlaywrightCapture won’t take a screenshot of the rendered URL
- **with_favicon** (bool) - Optional - If True, PlaywrightCapture will attempt to get the potential favicons for the rendered URL.
- **with_trusted_timestamps** (bool) - Optional - If True, PlaywrightCapture will trigger calls to a remote timestamp service.
- **allow_tracking** (bool) - Optional - If True, PlaywrightCapture will attempt to click through the cookie banners.
- **remote_headfull** (bool) - Optional - If True, the capture will be handled as a remote headfull session.
- **headless** (bool) - Optional - Whether to run the browser in headless mode. WARNING: requires to run in a graphical environment.
- **max_retries** (int) - Optional - The maximum number of retries for this capture
- **init_script** (str) - Optional - A JavaScript that will be executed on each page of the capture.
- **final_wait** (int) - Optional - The very last wait time, after the instrumentation is done.
- **force** (bool) - Optional - Force recapture, even if the same one was already done within the recapture_interval
- **recapture_interval** (int) - Optional - The time the enqueued settings are kept in memory to avoid duplicates
- **priority** (int) - Optional - The priority of the capture
- **uuid** (str) - Optional - The preset priority of the capture, auto-generated if not present.

### Returns
#### Success Response
- **uuid** (str) - UUID, reference to the capture for later use
```

--------------------------------

### check_redis_up()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Checks if the Redis service is operational. This method is part of the LacusCore class.

```APIDOC
## check_redis_up()

### Description
Checks if the Redis service is operational.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### LacusCore Class

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

The main class for initiating and managing web captures. It allows configuration of various capture parameters such as timeouts, proxies, and browser settings.

```APIDOC
## Class lacuscore.LacusCore

### Description
Capture URLs or web enabled documents using PlaywrightCapture.

### Parameters
* **redis_connector** (Redis[bytes]) - Pre-configured connector to a redis instance.
* **max_capture_time** (int) - If the capture takes more than that time, break (in seconds). Default: 3600.
* **expire_results** (int) - The capture results are stored in redis. Expire them after they are done (in seconds). Default: 36000.
* **tor_proxy** (dict[str, str] | str | None) - URL to a SOCKS5 tor proxy. If you have tor installed, this is the default: socks5://127.0.0.1:9050.
* **i2p_proxy** (dict[str, str] | str | None) - URL to a HTTP I2P proxy. If you have i2p installed, this is the default: http://127.0.0.1:4444.
* **only_global_lookups** (bool) - Discard captures that point to non-public IPs. Default: True.
* **max_retries** (int) - How many times should we re-try a capture if it failed. Default: 3.
* **headed_allowed** (bool) - Allow to launch captures in a local headed browser. Default: False.
* **remote_headed_allowed** (bool) - Allow to trigger a capture in a remote headed browser. Default: False.
* **remote_headed_backend_type** (str | None) - The backend type for the remote headed captures (curently, Xpra).
* **tt_settings** (TrustedTimestampSettings | None) - The settings for the Trusted Timestamps.
* **loglevel** (str | int) - Default: 'INFO'.
```

--------------------------------

### enqueue

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Adds a capture task to the queue with specified settings. Supports various parameters for URL, document content, browser options, and more.

```APIDOC
## Method enqueue

### Description
Enqueue settings.

### Parameters
* **settings** (CaptureSettings | dict[str, Any] | None) - General capture settings.
* **url** (str | None) - The URL to capture.
* **document_name** (str | None) - The name of the document to capture.
* **document** (str | None) - The content of the document to capture.
* **depth** (int) - Depth for crawling. Default: 0.
* **browser** (Literal['chromium', 'firefox', 'webkit'] | None) - The browser engine to use for capture.
* **device_name** (str | None) - The name of the device to emulate.
* **user_agent** (str | None) - Custom user agent string.
* **proxy** (str | dict[str, str] | None) - Proxy configuration.
* **socks5_dns_resolver** (str | list[str] | None) - SOCKS5 DNS resolver configuration.
* **general_timeout_in_sec** (int | None) - General timeout for the capture in seconds.
* **cookies** (list[dict[str, Any]] | list[Cookie] | None) - List of cookies to use for the capture.
* **storage** (dict[str, Any] | None) - Storage options for the capture.
* **headers** (dict[str, str] | None) - Custom HTTP headers.
* **http_credentials** (dict[str, str] | HttpCredentialsSettings | None) - HTTP authentication credentials.
* **geolocation** (dict[str, str | int | float] | GeolocationSettings | None) - Geolocation settings.
* **timezone_id** (str | None) - Timezone ID for the capture.
* **locale** (str | None) - Locale settings for the capture.
* **color_scheme** (str | None) - Color scheme preference (e.g., 'dark', 'light').
* **java_script_enabled** (bool) - Whether JavaScript should be enabled. Default: True.
* **viewport** (dict[str, int | str] | ViewportSettings | None) - Viewport settings for the browser.
* **referer** (str | None) - Referer header for the request.
* **rendered_hostname_only** (bool) - Whether to only capture the rendered hostname. Default: True.
* **with_screenshot** (bool) - Whether to include a screenshot in the capture. Default: True.
* **with_favicon** (bool) - Whether to include the favicon in the capture. Default: False.
* **with_trusted_timestamps** (bool) - Whether to include trusted timestamps. Default: False.
* **allow_tracking** (bool) - Whether to allow tracking. Default: False.
* **headless** (bool) - Whether to run the browser in headless mode. Default: True.
* **remote_headfull** (bool) - Whether to use a remote headful browser. Default: False.
* **max_retries** (int | None) - Maximum retries for the capture.
* **init_script** (str | None) - JavaScript to run before the page loads.
* **force** (bool) - Force re-capture even if results exist. Default: False.
* **recapture_interval** (int) - Interval in seconds to consider for re-capturing. Default: 300.
* **final_wait** (int) - Additional wait time in seconds after page load. Default: 5.
* **priority** (int) - Priority of the capture task. Default: 0.
* **uuid** (str | None) - A specific UUID for the capture task.

### Returns
* str - The unique identifier (UUID) of the enqueued capture task.
```

--------------------------------

### request_finish

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Marks a remote headfull session as ready for final capture.

```APIDOC
## request_finish

### Description
Marks a remote headfull session as ready for final capture.

### Method
POST (assumed)

### Endpoint
/request/finish/{uuid}

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture.

### Response
#### Success Response
- **bool** - True if the session was marked as ready, False otherwise.
- **dict[str, Any]** or **None** - The updated metadata, or None if no session exists.

### Response Example
```json
{
  "updated_metadata": "some_data"
}

```

--------------------------------

### request_finish

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Marks a remote headfull session as ready for final capture.

```APIDOC
## request_finish

### Description
Marks a remote headfull session as ready for final capture.

### Method
POST

### Endpoint
/session/{uuid}/finish

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the remote headfull session

### Returns
#### Success Response
- **bool** - True if the session was marked as finished, False otherwise.
- **dict[str, Any]** or **None** - The updated metadata, or None if no session exists.
```

--------------------------------

### playwright_devices

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves a list of devices that are exposed by Playwright.

```APIDOC
## playwright_devices

### Description
Gets the devices exposed by Playwright.

### Method
GET (assumed)

### Endpoint
/playwright/devices

### Response
#### Success Response
- **dict[str, Any]** - A dictionary containing information about Playwright devices.

### Response Example
```json
{
  "Pixel 5": {
    "name": "Pixel 5",
    "userAgent": "Mozilla/5.0 (Linux; Android 11; Pixel 5 Build/RP1A.201005.009; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/90.0.4430.91 Mobile Safari/537.36",
    "viewport": {
      "width": 360,
      "height": 720,
      "deviceScaleFactor": 2.75,
      "isMobile": true,
      "hasTouch": true,
      " உருவமைப்பு": "vertical"
    }
  }
}

```

--------------------------------

### Trigger Captures from Queue

Source: https://lacuscore.readthedocs.io/en/latest/_sources/index.rst.txt

Consumes and triggers up to a specified number of captures from the queue asynchronously. Requires a running Redis/Valkey instance.

```python
import asyncio

from redis import Redis

from lacuscore import LacusCore

redis = Redis()  # Connector to a running Redis/Valkey instance
lacus = LacusCore(redis)

async def run_captures() -> None:
    max_captures_to_consume = 10
    captures = set()
    for capture_task in lacus.consume_queue(max_captures_to_consume):
        captures.add(capture_task)  # adds the task to the set
        capture_task.add_done_callback(captures.discard)  # remove the task from the set when done

    await asyncio.gather(*captures)  # wait for all tasks to complete

asyncio.run(run_captures())
```

--------------------------------

### LacusCore.playwright_devices()

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Returns a list of available Playwright devices. This method is part of the LacusCore class.

```APIDOC
## LacusCore.playwright_devices()

### Description
Returns a list of available Playwright devices.

### Method
[Method signature or HTTP method if applicable]

### Parameters
None

### Response
- **devices**: list - A list of Playwright device configurations.
```

--------------------------------

### get_capture_env()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Retrieves the capture environment. This method is part of the XpraSessionManager class.

```APIDOC
## get_capture_env()

### Description
Retrieves the capture environment.

### Method
(Not specified, likely a method call within the XpraSessionManager class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### stop_session

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Terminates a running xpra backend session by delegating to the `xpra stop` command. It returns whether shutdown was confirmed or the backend already appeared to be gone.

```APIDOC
## stop_session

### Description
Terminates a running xpra backend session. The implementation delegates to the `xpra stop` command, targeting the display associated with this session. This keeps the shutdown logic in xpra itself and avoids relying on PIDs being stable across restarts.
If the session is already gone or xpra is not reachable, the call is treated as a best-effort no-op. The return value signals whether shutdown was confirmed or the backend already appeared to be gone. This method does not perform any Redis or higher-level cleanup; that must be handled by the caller.

### Method
None

### Endpoint
None

### Parameters
#### Path Parameters
- **_session** (Session) - Description not provided in source.
- **_uuid** (str) - Description not provided in source.
- **_metadata** (SessionMetadata) - Description not provided in source.
- **_status** (SessionStatus) - Description not provided in source.
- **_expire_seconds** (int) - Description not provided in source.

### Request Example
None

### Response
#### Success Response
- **bool** - True if shutdown was confirmed, False if the backend already appeared to be gone.

#### Response Example
None
```

--------------------------------

### check_redis_up

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Checks if the Redis instance connected to LacusCore is reachable.

```APIDOC
## Method check_redis_up

### Description
Check if redis is reachable

### Returns
* bool - True if Redis is up, False otherwise.
```

--------------------------------

### check_redis_up

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Checks if the Redis instance connected to LacusCore is reachable.

```APIDOC
## check_redis_up

### Description
Checks if the Redis instance connected to LacusCore is reachable.

### Method
GET

### Endpoint
/check_redis_up

### Returns
* **bool** - True if Redis is reachable, False otherwise.
```

--------------------------------

### get_capture_env

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Returns environment variables that should be passed to the capture process for a given session.

```APIDOC
## get_capture_env

### Description
Returns environment variables to pass to the capture process for a given session.

### Method
None

### Endpoint
None

### Parameters
#### Path Parameters
- **_session** (Session) - Description not provided in source.

### Request Example
None

### Response
#### Success Response
- **Mapping[str, str | float | bool]** - A mapping of environment variable names to their values.

#### Response Example
None
```

--------------------------------

### LacusCore.request_finish()

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Requests the finish of a capture or session. This method is part of the LacusCore class.

```APIDOC
## LacusCore.request_finish()

### Description
Requests the finish of a capture or session.

### Method
[Method signature or HTTP method if applicable]

### Parameters
- **capture_id**: [type] - Required - The ID of the capture or session to finish.

### Response
[Details about the response, e.g., confirmation of the request]
```

--------------------------------

### enqueue

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Enqueues a capture task with specified settings. This method can be called with various parameters to define the capture job, including URL, document content, browser type, and more.

```APIDOC
## enqueue

### Description
Enqueues a capture task with specified settings. This method can be called with various parameters to define the capture job, including URL, document content, browser type, and more.

### Method
POST

### Endpoint
/enqueue

### Parameters
#### Request Body
* **url** (str | None) - The URL to capture.
* **document_name** (str | None) - The name of the document to capture.
* **document** (str | None) - The content of the document to capture.
* **depth** (int) - The capture depth. Default: 0.
* **browser** (Literal['chromium', 'firefox', 'webkit'] | None) - The browser to use for capture.
* **device_name** (str | None) - The name of the device to emulate.
* **user_agent** (str | None) - The user agent string to use.
* **proxy** (str | dict[str, str] | None) - Proxy settings.
* **socks5_dns_resolver** (str | list[str] | None) - SOCKS5 DNS resolver.
* **general_timeout_in_sec** (int | None) - General timeout in seconds.
* **cookies** (list[dict[str, Any]] | list[Cookie] | None) - Cookies to use for the capture.
* **storage** (dict[str, Any] | None) - Storage settings.
* **headers** (dict[str, str] | None) - Custom headers.
* **http_credentials** (dict[str, str] | HttpCredentialsSettings | None) - HTTP credentials.
* **geolocation** (dict[str, str | int | float] | GeolocationSettings | None) - Geolocation settings.
* **timezone_id** (str | None) - Timezone ID.
* **locale** (str | None) - Locale settings.
* **color_scheme** (str | None) - Color scheme preference.
* **java_script_enabled** (bool) - Whether JavaScript is enabled. Default: True.
* **viewport** (dict[str, int | str] | ViewportSettings | None) - Viewport settings.
* **referer** (str | None) - Referer header.
* **rendered_hostname_only** (bool) - Whether to capture only the rendered hostname. Default: True.
* **with_screenshot** (bool) - Whether to include a screenshot. Default: True.
* **with_favicon** (bool) - Whether to include the favicon. Default: False.
* **with_trusted_timestamps** (bool) - Whether to include trusted timestamps. Default: False.
* **allow_tracking** (bool) - Whether to allow tracking. Default: False.
* **headless** (bool) - Whether to run in headless mode. Default: True.
* **remote_headfull** (bool) - Whether to run in remote headfull mode. Default: False.
* **max_retries** (int | None) - Maximum retries for the capture.
* **init_script** (str | None) - Initialization script.
* **force** (bool) - Force capture. Default: False.
* **recapture_interval** (int) - Recapture interval in seconds. Default: 300.
* **final_wait** (int) - Final wait time in seconds. Default: 5.
* **priority** (int) - Priority of the capture task. Default: 0.
* **uuid** (str | None) - Unique identifier for the capture task.

### Returns
* **str** - The unique identifier of the enqueued capture task.
```

--------------------------------

### playwright_devices()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Returns a list of Playwright devices. This method is part of the LacusCore class.

```APIDOC
## playwright_devices()

### Description
Returns a list of Playwright devices.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### get_session_backend_metadata()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Retrieves metadata for the session backend. This method is part of the LacusCore class.

```APIDOC
## get_session_backend_metadata()

### Description
Retrieves metadata for the session backend.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### stop_session()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Stops an existing session. This method is part of the XpraSessionManager class.

```APIDOC
## stop_session()

### Description
Stops an existing session.

### Method
(Not specified, likely a method call within the XpraSessionManager class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### consume_queue()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Consumes items from a queue. This method is part of the LacusCore class.

```APIDOC
## consume_queue()

### Description
Consumes items from a queue.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### LacusCore.get_capture()

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves a capture. This method is part of the LacusCore class.

```APIDOC
## LacusCore.get_capture()

### Description
Retrieves a capture.

### Method
[Method signature or HTTP method if applicable]

### Parameters
- **capture_id**: [type] - Required - The ID of the capture to retrieve.

### Response
- **CaptureResponseJson**: The capture data.

### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### consume_queue

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Processes and triggers captures from the queue based on priority, up to a specified limit.

```APIDOC
## Method consume_queue

### Description
Trigger the capture for captures with the highest priority. Up to max_consume.

### Parameters
* **max_consume** (int) - The maximum number of captures to process from the queue.

### Yields
* Task[None] - Represents the ongoing capture tasks.
```

--------------------------------

### get_capture()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Retrieves the current capture. This method is part of the LacusCore class.

```APIDOC
## get_capture()

### Description
Retrieves the current capture.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### request_finish()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Signals the end of a request. This method is part of the LacusCore class.

```APIDOC
## request_finish()

### Description
Signals the end of a request.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### get_session_metadata()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Retrieves metadata for the session. This method is part of the LacusCore class.

```APIDOC
## get_session_metadata()

### Description
Retrieves metadata for the session.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### get_capture

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves the results of a capture using its UUID. The results can be returned in a decoded format or as raw JSON.

```APIDOC
## get_capture

### Description
Retrieves the results of a capture using its UUID. The results can be returned in a decoded format or as raw JSON.

### Method
GET

### Endpoint
/capture/{uuid}

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture (given by enqueue)

#### Query Parameters
- **decode** (bool) - Optional - Decode the capture result or not. Defaults to True.

### Returns
#### Success Response
- **CaptureResponse** or **CaptureResponseJson** - The capture, decoded or not.
```

--------------------------------

### get_capture

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves the results of a capture. The results can be decoded into a Python object or returned as a JSON-compatible format.

```APIDOC
## get_capture

### Description
Retrieves the results of a capture, with an option to decode the response.

### Method
GET (assumed)

### Endpoint
/capture/{uuid}

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture.

#### Query Parameters
- **decode** (bool) - Optional - Defaults to True. If True, decodes the capture result. If False, returns a JSON-compatible format.

### Response
#### Success Response
- **CaptureResponse** or **CaptureResponseJson** - The capture result, decoded or in JSON format.

### Request Example
```json
{
  "uuid": "some-uuid-string",
  "decode": true
}
```

### Response Example
```json
{
  "example": "Decoded capture response or JSON compatible response"
}

```

--------------------------------

### consume_queue

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Triggers the capture process for the highest priority tasks in the queue, up to a specified maximum number.

```APIDOC
## consume_queue

### Description
Triggers the capture process for the highest priority tasks in the queue, up to a specified maximum number.

### Method
POST

### Endpoint
/consume_queue

### Parameters
#### Query Parameters
* **max_consume** (int) - Required - The maximum number of captures to consume from the queue.

### Yields
* **Task[None]** - Represents the capture tasks being processed.
```

--------------------------------

### get_session_backend_metadata

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves backend-specific metadata for trusted session transport callers, identified by a capture UUID.

```APIDOC
## get_session_backend_metadata

### Description
Retrieves backend-specific metadata for trusted session transport callers, identified by a capture UUID.

### Method
GET

### Endpoint
/session/{uuid}/backend_metadata

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture

### Returns
#### Success Response
- **dict[str, Any]** or **None** - Backend-specific metadata or None if no session exists.
```

--------------------------------

### get_session_backend_metadata

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves backend-specific metadata for trusted session transport callers associated with a capture UUID.

```APIDOC
## get_session_backend_metadata

### Description
Returns backend-specific metadata for trusted session transport callers.

### Method
GET (assumed)

### Endpoint
/session/backend-metadata/{uuid}

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture.

### Response
#### Success Response
- **dict[str, Any]** or **None** - Backend-specific metadata or None if no session exists.

### Response Example
```json
{
  "metadata_key": "metadata_value"
}

```

--------------------------------

### cleanup_expired_sessions()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Cleans up sessions that have expired. This method belongs to the XpraSessionManager class.

```APIDOC
## cleanup_expired_sessions()

### Description
Cleans up sessions that have expired.

### Method
(Not specified, likely a method call within the XpraSessionManager class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### get_capture_status()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Retrieves the status of the capture. This method is part of the LacusCore class.

```APIDOC
## get_capture_status()

### Description
Retrieves the status of the capture.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### clear_capture

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Removes a capture from the system, typically used when a capture encounters an error.

```APIDOC
## Method clear_capture

### Description
Remove a capture from the list, shouldn’t happen unless it is in error

### Parameters
* **uuid** (str) - The unique identifier of the capture to remove.
* **reason** (str) - The reason for clearing the capture.
```

--------------------------------

### get_session_metadata

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves public session metadata for a capture UUID.

```APIDOC
## get_session_metadata

### Description
Returns public session metadata for a capture UUID.

### Method
GET (assumed)

### Endpoint
/session/metadata/{uuid}

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture.

### Response
#### Success Response
- **SessionMetadata** or **None** - Public session metadata or None if no session exists.

### Response Example
```json
{
  "session_info": "some_session_details"
}

```

--------------------------------

### get_session_metadata

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves public session metadata for a given capture UUID.

```APIDOC
## get_session_metadata

### Description
Retrieves public session metadata for a given capture UUID.

### Method
GET

### Endpoint
/session/{uuid}

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture

### Returns
#### Success Response
- **SessionMetadata** or **None** - Public session metadata or None if no session exists.
```

--------------------------------

### clear_capture()

Source: https://lacuscore.readthedocs.io/en/latest/genindex.html

Clears the current capture. This method is part of the LacusCore class.

```APIDOC
## clear_capture()

### Description
Clears the current capture.

### Method
(Not specified, likely a method call within the LacusCore class)

### Endpoint
N/A (SDK method)

### Parameters
None explicitly documented.

### Request Example
N/A

### Response
(Not specified)
```

--------------------------------

### get_capture_status

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Retrieves the current status of a specified capture using its UUID.

```APIDOC
## get_capture_status

### Description
Gets the status of a capture identified by its UUID.

### Method
GET (assumed)

### Endpoint
/capture/status/{uuid}

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the capture.

### Response
#### Success Response
- **CaptureStatus** - The status of the capture.

### Response Example
```json
{
  "status": "completed"
}

```

--------------------------------

### clear_capture

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Removes a capture from the list, typically used when a capture is in an error state.

```APIDOC
## clear_capture

### Description
Removes a capture from the list, typically used when a capture is in an error state.

### Method
DELETE

### Endpoint
/captures/{uuid}

### Parameters
#### Path Parameters
* **uuid** (str) - Required - The unique identifier of the capture to remove.
* **reason** (str) - Required - The reason for clearing the capture.
```

--------------------------------

### cleanup_expired_sessions

Source: https://lacuscore.readthedocs.io/en/latest/api_reference.html

Stops remote headed sessions whose TTL has expired. This method scans session metadata, stops expired xpra processes, and marks their status as 'expired'. It is intended for periodic calls by an external scheduler.

```APIDOC
## cleanup_expired_sessions

### Description
Stops remote headed sessions whose TTL has expired. This method scans all remote headed session metadata keys and, for any session whose `expires_at` is in the past and whose status is not already terminal (“stopped” or “expired”), stops the underlying xpra process and marks the status as “expired”.
It is designed to be called periodically by an external scheduler.

### Method
None (designed to be called periodically by an external scheduler)

### Endpoint
None

### Parameters
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```
Tokens:
Raw