Metadata-Version: 2.4
Name: lacuscore
Version: 1.24.7
Summary: Core of Lacus, usable as a module
License-Expression: BSD-3-Clause
License-File: LICENSE
Author: Raphaël Vinot
Author-email: raphael.vinot@circl.lu
Requires-Python: >=3.10,<3.15
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Security
Provides-Extra: docs
Requires-Dist: Sphinx (>=9.1.0) ; (python_version >= "3.12") and (extra == "docs")
Requires-Dist: async-timeout (>=5.0.1) ; python_version < "3.11"
Requires-Dist: dnspython (>=2.8.0)
Requires-Dist: lookyloo-models (>=0.2.5)
Requires-Dist: playwrightcapture[recaptcha] (>=1.39.7)
Requires-Dist: pydantic (>=2.13.3)
Requires-Dist: redis[hiredis] (>=5.3.0,<6.0.0)
Requires-Dist: typing-extensions (>=4.12.2,<5.0.0) ; python_version < "3.12"
Project-URL: Documentation, https://lacuscore.readthedocs.io/en/latest/
Project-URL: Issues, https://github.com/ail-project/issues
Project-URL: Repository, https://github.com/ail-project/LacusCore
Description-Content-Type: text/markdown

[![Documentation Status](https://readthedocs.org/projects/lacuscore/badge/?version=latest)](https://lacuscore.readthedocs.io/en/latest/?badge=latest)

# Modulable Lacus

Lacus, but as a simple module.

# Installation

```bash
pip install lacuscore
```

# Design

`LacusCore` is the part taking care of enqueuing and capturing URLs or web enabled documents.
It can be used as a module in your own project, see below for the usage

[Lacus](https://github.com/ail-project/lacus) is the webservice that uses `LacusCore`,
and you can use [Pylacus](https://github.com/ail-project/pylacus) to query it.

The `enqueue`, `get_capture_status`, and `get_capture` methods if `LacusCore` and `PyLacus` have
the same parameters which means you can easily use them interchangeably in your project.

## Interactive Sessions

`LacusCore` can also manage interactive captures when it is initialized with
`interactive_allowed=True` and `headed_allowed=True`. In that mode, `enqueue(...)`
accepts `interactive=True` (and an optional `interactive_ttl` in seconds,
default 600) and keeps the browser session alive until a trusted caller
triggers the final capture via `request_session_capture(uuid)`.

Interactive session state is split into two layers:

- `get_session_metadata(uuid)` returns the backend-agnostic public state for a
	session: status, view URL, lifecycle timestamps, and whether a final capture
	has been requested.
- `get_session_backend_metadata(uuid)` returns backend-specific transport data
	for trusted local infrastructure only. This is where implementation details
	such as xpra unix socket paths belong.

That split keeps API consumers decoupled from the current xpra implementation
while still allowing a local sidecar proxy to connect to the active session.


For more information regarding the usage of the module and a few examples, please refer to
[the documentation](https://lacuscore.readthedocs.io/en/latest/)

