# Shared Resource Decorator
[](https://pypi.python.org/pypi/vedro-shared-resource/)
[](https://pypi.python.org/pypi/vedro-shared-resource/)
[](https://pypi.python.org/pypi/vedro-shared-resource/)
This package provides a simple decorator, `@shared_resource()`, which allows creation and sharing of resource instances between tests. Instead of repeatedly creating and then closing (or finalizing) the same resource in every test, a resource can be created once, shared across tests, and automatically finalized after all tests have finished.
## Installation
Install the package via pip:
```bash
pip install vedro-shared-resource
```
## Overview
In some testing scenarios, a resource is created and then closed or finalized separately in each test. For example:
```python
# Test 1
resource = create_resource()
defer(resource.close)
# do something with resource
# Test 2
resource = create_resource()
defer(resource.close)
# do something with resource
```
*(Note: Here, the `defer` function registers a callback to be executed after the current test scenario finishes)*
Repeatedly creating the resource can lead to longer test execution times and increased resource consumption. By defining a shared resource that is created only once and cached using `@shared_resource()`, tests can run faster while ensuring that:
- **Performance Improvement:** Expensive resource initialization is executed only once per unique set of arguments.
- **Consistency:** All tests that request the resource with the same parameters receive the same shared instance.
- **Resource Management:** The resource is finalized (closed) only once after all tests complete, reducing the risk of resource leaks.
## Usage
### 1. Creating a Shared Resource
To share a resource, wrap the resource-creation function with the `@shared_resource()` decorator. Within the function, use `defer_global` to register the resource’s finalization callback.
```python
from vedro_shared_resource import shared_resource
from vedro import defer_global
@shared_resource()
def create_shared_resource():
resource = create_resource()
defer_global(resource.close)
return resource
```
*(Note: While `defer` registers a callback for the current test scenario, `defer_global` registers a callback for the entire test suite)*
### 2. Using the Shared Resource in Tests
When the decorated function is called in tests, the first call executes the function and caches its result. Subsequent calls return the cached resource immediately, avoiding redundant and expensive resource creation.
```python
# Test 1
resource = create_shared_resource()
# perform operations with resource
# Test 2
resource = create_shared_resource()
# perform operations with resource
```
## The `@shared_resource()` Decorator
The `@shared_resource()` decorator caches the result of the resource creation function:
- **First call:** The resource creation function is executed, and its result is stored in a cache.
- **Subsequent calls:** The cached resource is returned immediately, avoiding the expense of re-creating the resource.
If the function accepts arguments, they become part of the cache key, ensuring that each unique combination of arguments results in a separate cached resource.
### Parameters
- **max_instances (int):**
Specifies the maximum number of unique cached results for the function. This limit is applied per resource function. Once the cache reaches this size, the least-recently-used entry is evicted.
- **type_sensitive (bool):**
If set to `True`, arguments of different types (for example, `1` vs. `1.0`) are treated as distinct cache keys.
### Under the Hood
- For **synchronous functions**, the decorator leverages Python's built-in `functools.lru_cache`.
- For **asynchronous functions**, it utilizes `async_lru.alru_cache`.
## Use Cases Examples
### Use Case 1: Sharing an Asynchronous Resource (HTTP Client)
An asynchronous HTTP client from the `httpx` library can be shared between tests. Although instantiating an `AsyncClient` might not be highly resource-intensive by itself, [the official httpx documentation](https://www.python-httpx.org/async/#opening-and-closing-clients) recommends reusing a single client instance to take full advantage of connection pooling. Instantiating multiple clients—especially inside a "hot loop"—can prevent efficient reuse of connections. Caching the client instance ensures that it is created only once and reused throughout the test suite, supporting optimal connection pooling.
```python
from vedro_shared_resource import shared_resource
from vedro import defer_global
from httpx import AsyncClient
@shared_resource()
async def async_client() -> AsyncClient:
client = AsyncClient()
await client.__aenter__()
defer_global(client.aclose)
return client
```
Usage in tests:
```python
client = await async_client()
response = await client.get("https://example.com")
```
*(This is just an example. For better integration with httpx, consider using the [vedro-httpx](https://pypi.org/project/vedro-httpx/) plugin)*
### Use Case 2: Sharing a Synchronous Resource (Web Browser)
Sharing a Chromium browser instance while accepting parameters allows different configurations to be cached separately. The resource creation function uses keyword arguments as part of the cache key, meaning that launching the Chromium browser with specified parameters (e.g., `headless=False`) is performed only once per configuration. Because launching a browser repeatedly can significantly slow down tests, caching the launched browser instance improves performance and ensures consistency across tests.
```python
from vedro_shared_resource import shared_resource
from vedro import defer_global
from playwright.sync_api import sync_playwright, Browser
@shared_resource()
def chromium(**kwargs) -> Browser:
playwright = sync_playwright().start()
defer_global(playwright.stop)
chromium = playwright.chromium.launch(**kwargs)
defer_global(chromium.close)
return chromium
```
Usage in tests:
```python
browser = chromium(headless=False)
page = browser.new_page()
page.goto("https://example.com")
```
*(This is just an example. For better integration with Playwright, consider using the [vedro-pw](https://pypi.org/project/vedro-pw/) plugin)*
## Caveats and Considerations
Introducing global variables and any kind of caching can sometimes lead to unexpected issues, such as shared state conflicts or challenges with test isolation. It is recommended to use resource caching only when resource creation is a true bottleneck and when sharing a resource does not compromise the reliability and correctness of tests.
Raw data
{
"_id": null,
"home_page": "https://github.com/vedro-universe/vedro-shared-resource",
"name": "vedro-shared-resource",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Nikita Tsvetkov",
"author_email": "tsv1@fastmail.com",
"download_url": "https://files.pythonhosted.org/packages/25/b7/8fa49e83d2bbff4ebc220f0401cae69d7456a938821a75bcfef78ec27db3/vedro_shared_resource-0.2.1.tar.gz",
"platform": null,
"description": "# Shared Resource Decorator\n\n[](https://pypi.python.org/pypi/vedro-shared-resource/)\n[](https://pypi.python.org/pypi/vedro-shared-resource/)\n[](https://pypi.python.org/pypi/vedro-shared-resource/)\n\nThis package provides a simple decorator, `@shared_resource()`, which allows creation and sharing of resource instances between tests. Instead of repeatedly creating and then closing (or finalizing) the same resource in every test, a resource can be created once, shared across tests, and automatically finalized after all tests have finished.\n\n## Installation\n\nInstall the package via pip:\n\n```bash\npip install vedro-shared-resource\n```\n\n## Overview\n\nIn some testing scenarios, a resource is created and then closed or finalized separately in each test. For example:\n\n```python\n# Test 1\nresource = create_resource()\ndefer(resource.close)\n# do something with resource\n\n# Test 2\nresource = create_resource()\ndefer(resource.close)\n# do something with resource\n```\n\n*(Note: Here, the `defer` function registers a callback to be executed after the current test scenario finishes)*\n\nRepeatedly creating the resource can lead to longer test execution times and increased resource consumption. By defining a shared resource that is created only once and cached using `@shared_resource()`, tests can run faster while ensuring that:\n- **Performance Improvement:** Expensive resource initialization is executed only once per unique set of arguments.\n- **Consistency:** All tests that request the resource with the same parameters receive the same shared instance.\n- **Resource Management:** The resource is finalized (closed) only once after all tests complete, reducing the risk of resource leaks.\n\n## Usage\n\n### 1. Creating a Shared Resource\n\nTo share a resource, wrap the resource-creation function with the `@shared_resource()` decorator. Within the function, use `defer_global` to register the resource\u2019s finalization callback.\n\n```python\nfrom vedro_shared_resource import shared_resource\nfrom vedro import defer_global\n\n@shared_resource()\ndef create_shared_resource():\n resource = create_resource()\n defer_global(resource.close)\n return resource\n```\n\n*(Note: While `defer` registers a callback for the current test scenario, `defer_global` registers a callback for the entire test suite)*\n\n### 2. Using the Shared Resource in Tests\n\nWhen the decorated function is called in tests, the first call executes the function and caches its result. Subsequent calls return the cached resource immediately, avoiding redundant and expensive resource creation.\n\n```python\n# Test 1\nresource = create_shared_resource()\n# perform operations with resource\n\n# Test 2\nresource = create_shared_resource()\n# perform operations with resource\n```\n\n## The `@shared_resource()` Decorator\n\nThe `@shared_resource()` decorator caches the result of the resource creation function:\n\n- **First call:** The resource creation function is executed, and its result is stored in a cache.\n- **Subsequent calls:** The cached resource is returned immediately, avoiding the expense of re-creating the resource.\n\nIf the function accepts arguments, they become part of the cache key, ensuring that each unique combination of arguments results in a separate cached resource.\n\n### Parameters\n\n- **max_instances (int):** \n Specifies the maximum number of unique cached results for the function. This limit is applied per resource function. Once the cache reaches this size, the least-recently-used entry is evicted.\n\n- **type_sensitive (bool):** \n If set to `True`, arguments of different types (for example, `1` vs. `1.0`) are treated as distinct cache keys.\n\n### Under the Hood\n\n- For **synchronous functions**, the decorator leverages Python's built-in `functools.lru_cache`.\n- For **asynchronous functions**, it utilizes `async_lru.alru_cache`.\n\n## Use Cases Examples\n\n### Use Case 1: Sharing an Asynchronous Resource (HTTP Client)\n\nAn asynchronous HTTP client from the `httpx` library can be shared between tests. Although instantiating an `AsyncClient` might not be highly resource-intensive by itself, [the official httpx documentation](https://www.python-httpx.org/async/#opening-and-closing-clients) recommends reusing a single client instance to take full advantage of connection pooling. Instantiating multiple clients\u2014especially inside a \"hot loop\"\u2014can prevent efficient reuse of connections. Caching the client instance ensures that it is created only once and reused throughout the test suite, supporting optimal connection pooling.\n\n```python\nfrom vedro_shared_resource import shared_resource\nfrom vedro import defer_global\nfrom httpx import AsyncClient\n\n@shared_resource()\nasync def async_client() -> AsyncClient:\n client = AsyncClient()\n await client.__aenter__()\n\n defer_global(client.aclose)\n\n return client\n```\n\nUsage in tests:\n\n```python\nclient = await async_client()\nresponse = await client.get(\"https://example.com\")\n```\n\n*(This is just an example. For better integration with httpx, consider using the [vedro-httpx](https://pypi.org/project/vedro-httpx/) plugin)*\n\n### Use Case 2: Sharing a Synchronous Resource (Web Browser)\n\nSharing a Chromium browser instance while accepting parameters allows different configurations to be cached separately. The resource creation function uses keyword arguments as part of the cache key, meaning that launching the Chromium browser with specified parameters (e.g., `headless=False`) is performed only once per configuration. Because launching a browser repeatedly can significantly slow down tests, caching the launched browser instance improves performance and ensures consistency across tests.\n\n```python\nfrom vedro_shared_resource import shared_resource\nfrom vedro import defer_global\nfrom playwright.sync_api import sync_playwright, Browser\n\n@shared_resource()\ndef chromium(**kwargs) -> Browser:\n playwright = sync_playwright().start()\n defer_global(playwright.stop)\n\n chromium = playwright.chromium.launch(**kwargs)\n defer_global(chromium.close)\n\n return chromium\n```\n\nUsage in tests:\n\n```python\nbrowser = chromium(headless=False)\npage = browser.new_page()\npage.goto(\"https://example.com\")\n```\n\n*(This is just an example. For better integration with Playwright, consider using the [vedro-pw](https://pypi.org/project/vedro-pw/) plugin)*\n\n## Caveats and Considerations\n\nIntroducing global variables and any kind of caching can sometimes lead to unexpected issues, such as shared state conflicts or challenges with test isolation. It is recommended to use resource caching only when resource creation is a true bottleneck and when sharing a resource does not compromise the reliability and correctness of tests.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A decorator for sharing costly resources between tests efficiently",
"version": "0.2.1",
"project_urls": {
"Docs": "https://github.com/vedro-universe/vedro-shared-resource",
"GitHub": "https://github.com/vedro-universe/vedro-shared-resource",
"Homepage": "https://github.com/vedro-universe/vedro-shared-resource"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "869cee2e6cfacd2d514766405f7ec989598374c3a741e27160bb87306966dadd",
"md5": "c765b06b13c9abde7cef34132036a0ce",
"sha256": "68064d305d1cb32358284b73f438c9996d4bda46fb16c48e4ed13d8f90c06c0c"
},
"downloads": -1,
"filename": "vedro_shared_resource-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c765b06b13c9abde7cef34132036a0ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9227,
"upload_time": "2025-02-23T10:36:57",
"upload_time_iso_8601": "2025-02-23T10:36:57.365361Z",
"url": "https://files.pythonhosted.org/packages/86/9c/ee2e6cfacd2d514766405f7ec989598374c3a741e27160bb87306966dadd/vedro_shared_resource-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "25b78fa49e83d2bbff4ebc220f0401cae69d7456a938821a75bcfef78ec27db3",
"md5": "6208470d6a18eb8cb8f4e90c787d5df6",
"sha256": "1ac3d8e46e90c706b26dbb37cee4fe0cc870df9a7915647bdec936457c94cb6d"
},
"downloads": -1,
"filename": "vedro_shared_resource-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "6208470d6a18eb8cb8f4e90c787d5df6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8930,
"upload_time": "2025-02-23T10:36:59",
"upload_time_iso_8601": "2025-02-23T10:36:59.394793Z",
"url": "https://files.pythonhosted.org/packages/25/b7/8fa49e83d2bbff4ebc220f0401cae69d7456a938821a75bcfef78ec27db3/vedro_shared_resource-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-23 10:36:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vedro-universe",
"github_project": "vedro-shared-resource",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "vedro",
"specs": [
[
">=",
"1.13"
],
[
"<",
"2.0"
]
]
},
{
"name": "async-lru",
"specs": [
[
">=",
"2.0"
],
[
"<",
"3.0"
]
]
}
],
"lcname": "vedro-shared-resource"
}
JSON
