Pook

https://pook.readthedocs.io/en/latest
Admin
Pook is a versatile Python utility library for HTTP traffic mocking and expectations that supports...
Tokens:75,453
Snippets:430
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Pook from Source Code Package

Source: https://pook.readthedocs.io/en/latest/_sources/install.rst

Installs Pook from a downloaded source code archive. This method involves downloading, extracting, and then running the setup script.

```bash
tar xvf pook-{version}.tar.gz
cd pook
python setup.py install
```

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

### Install Pook from Source Code Package

Source: https://pook.readthedocs.io/en/latest/install

Installs Pook from a downloaded source code package. This involves downloading the archive, extracting it, navigating to the directory, and then using setuptools to install the package.

```bash
$ tar xvf pook-{version}.tar.gz
$ cd pook
$ python setup.py install
```

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

### Install Pook from GitHub using pip

Source: https://pook.readthedocs.io/en/latest/_sources/install.rst

Installs the latest development version of Pook directly from its GitHub repository. This is useful for testing the newest features or contributing to the project.

```bash
pip install -e git+git://github.com/h2non/pook.git#egg=pook
```

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

### Using urllib3 as HTTP Client

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Demonstrates mocking HTTP requests made using the 'urllib3' library. This example shows how to set up mock responses for urllib3 clients.

```python
from mocket import Mocketizer
import urllib3

with Mocketizer() as m:
    m.register('http://urllib3.com', content='Urllib3 mock')
    http = urllib3.PoolManager()
    response = http.request('GET', 'http://urllib3.com')
    assert response.data.decode('utf-8') == 'Urllib3 mock'
```

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

### Query Parameter Matching for GET Requests (Python)

Source: https://pook.readthedocs.io/en/latest/examples

Shows how to mock a GET request that matches specific query parameters. It enables the mock engine, defines a mock with `.params()`, and sends a request with matching parameters to verify.

```python
import requests

import pook

# Enable mock engine
pook.on()

    pook.get("httpbin.org/get")
    .params({"foo": "bar"})
    .reply(201)
    .json({"error": "simulated"})

res = requests.get("http://httpbin.org/get", params={"foo": "bar"})

assert res.status_code == 201
assert res.json() == {"error": "simulated"}
assert pook.isdone()
assert pook.pending_mocks() == []
```

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

### Install Pook from PyPI using pip

Source: https://pook.readthedocs.io/en/latest/_sources/install.rst

Installs the latest stable release of the Pook library from the Python Package Index (PyPI). This is the recommended method for most users.

```bash
pip install pook
```

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

### Basic Mocking with Requests Client

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Demonstrates how to use Mocket to mock HTTP requests made with the popular 'requests' library. This example shows setting up a mock response for a specific URL and asserting that the request was made correctly.

```python
from mocket import Mocketizer
import requests

with Mocketizer() as m:
    m.register('http://example.com', content='Mocked response')
    response = requests.get('http://example.com')
    assert response.text == 'Mocked response'
```

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

### Single Mock Context Manager Definition

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Demonstrates a concise way to define a single mock context manager for isolated mocking. This simplifies the setup when only one mock needs to be managed within a specific scope.

```python
from mocket import mocketize
import requests

@mocketize
def test_isolated_mock():
    mocketize.register('http://single.com', content='Single mock')
    response = requests.get('http://single.com')
    assert response.text == 'Single mock'
```

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

### Asynchronous HTTP Request using aiohttp

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Shows how to mock asynchronous HTTP requests made with the 'aiohttp' library. This example covers setting up mock responses for async operations.

```python
import asyncio
from mocket import Mocketizer
import aiohttp

async def fetch_async():
    async with aiohttp.ClientSession() as session:
        async with session.get('http://aiohttp.com') as response:
            return await response.text()

async def main():
    with Mocketizer() as m:
        m.register('http://aiohttp.com', content='Aiohttp mock')
        result = await fetch_async()
        assert result == 'Aiohttp mock'

asyncio.run(main())
```

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

### Using http.client Standard Python Package

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Demonstrates mocking HTTP requests made using Python's built-in 'http.client' package. This example shows how to configure mocks for native HTTP connections.

```python
from mocket import Mocketizer
import http.client

with Mocketizer() as m:
    m.register('http://httpclient.com', content='HTTP client mock')
    conn = http.client.HTTPConnection('httpclient.com')
    conn.request('GET', '/')
    response = conn.getresponse()
    data = response.read()
    assert data.decode('utf-8') == 'HTTP client mock'
```

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

### Basic Mocking with Requests

Source: https://pook.readthedocs.io/en/latest/examples

This example demonstrates basic HTTP request mocking using Pook with the `requests` library. It shows how to enable the mock engine, define GET requests with specific replies and headers, and then make requests to verify the mocks. It also includes checks for mock completion and unmatched requests.

```python
import requests

import pook

# Enable mock engine
pook.on()

pook.get(
    "httpbin.org/ip",
    reply=403,
    response_type="json",
    response_headers={"server": "pook"},
    response_json={"error": "not found"},
)

pook.get(
    "httpbin.org/headers",
    reply=404,
    response_type="json",
    response_headers={"server": "pook"},
    response_json={"error": "not found"},
)

res = requests.get("http://httpbin.org/ip")
print("Status:", res.status_code)
print("Headers:", res.headers)
print("Body:", res.json())

res = requests.get("http://httpbin.org/headers")
print("Status:", res.status_code)
print("Headers:", res.headers)
print("Body:", res.json())

print("Is done:", pook.isdone())
print("Pending mocks:", pook.pending_mocks())
print("Unmatched requests:", pook.unmatched_requests())

```

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

### Core API - get()

Source: https://pook.readthedocs.io/en/latest/api

A convenience method to set up a mock for a GET request. Equivalent to `on().get()`.

```APIDOC
## GET /api/status

### Description
Retrieves the current status of the service.

### Method
GET

### Endpoint
/api/status

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(No request body for GET requests)

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **status** (string) - The current status of the service (e.g., 'operational', 'degraded').

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

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

### Mock HTTP GET with http.client

Source: https://pook.readthedocs.io/en/latest/examples

This example shows how to mock an HTTP GET request using Pook with Python's built-in http.client. It enables Pook, defines a mock for http://httpbin.org/ip with a 404 reply, makes the request using http.client, and then prints the response status, headers, and body. It also demonstrates checking Pook's state with isdone(), pending_mocks(), and unmatched_requests().

```python
import http.client

import pook

# Enable mock engine
pook.on()

mock = pook.get(
    "http://httpbin.org/ip",
    reply=404,
    response_type="json",
    response_json={"error": "not found"},
)

conn = http.client.HTTPConnection("httpbin.org")
conn.request("GET", "/ip")

res = conn.getresponse()
print("Status:", res.status, res.reason)
print("Headers:", res.headers)
print("Body:", res.read())
print("Mock calls:", mock.calls)

print("Is done:", pook.isdone())
print("Pending mocks:", pook.pending_mocks())
print("Unmatched requests:", pook.unmatched_requests())
```

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

### Regular Expression Matching

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Shows how to use regular expressions to match request URLs. This provides flexibility when dealing with dynamic or complex URL patterns.

```python
from mocket import Mocketizer
import requests

with Mocketizer() as m:
    m.register(r'http://regex.com/d+', content='Regex matched')
    response = requests.get('http://regex.com/123')
    assert response.text == 'Regex matched'
```

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

### unittest Integration Example

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Demonstrates how to integrate Mocket with Python's built-in 'unittest' framework. This allows for mocking HTTP requests within unit tests.

```python
import unittest
from mocket import mocketize
import requests

class TestRequests(unittest.TestCase):
    @mocketize
    def test_mocked_request(self):
        mocketize.register('http://unittest.com', content='Unittest mock')
        response = requests.get('http://unittest.com')
        self.assertEqual(response.text, 'Unittest mock')
```

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

### Activating Mock Engine via Decorator

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Illustrates activating the mock engine using a decorator within a function's context. This is useful for enabling mocking for specific synchronous functions.

```python
from mocket import mocketize
import requests

@mocketize
def sync_request():
    mocketize.register('http://sync.com', content='Sync response')
    return requests.get('http://sync.com').text

assert sync_request() == 'Sync response'
```

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

### Pook Activation and Mocking

Source: https://pook.readthedocs.io/en/latest/api

This section covers the standard activation of Pook and how to mock specific HTTP requests, along with an example of making a request and asserting the response.

```APIDOC
## Pook Activation and Mocking

### Description
Activates Pook's HTTP traffic interceptors, allows mocking of specific URLs, and demonstrates making a request to a mocked endpoint.

### Method
N/A (Code examples)

### Endpoint
N/A (Code examples)

### Parameters
N/A

### Request Example
```python
import pook
import requests

# Standard use case
pook.activate()
pook.mock('server.com/foo').reply(404)

res = requests.get('server.com/foo')
assert res.status_code == 404
pook.disable()

# Decorator use case
@pook.activate
def test_request():
    pook.mock('server.com/foo').reply(404)

    res = requests.get('server.com/foo')
    assert res.status_code == 404
```

### Response
#### Success Response (200)
N/A (This section demonstrates mocking and assertion, not a direct API response)

#### Response Example
N/A
```

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

### Hy programming language example

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Provides an example of using Mocket with the Hy programming language, which is a Lisp dialect that runs on the JVM, .NET and Python. This demonstrates Mocket's flexibility across different language environments.

```hy
(require hy.contrib.mocket)
(require [requests :as req])

(with [(hy.contrib.mocket.Mocketizer) [m]]
  (m.register "http://hy.com" :content "Hy mock")
  (let [response (req.get "http://hy.com")]
    (assert (= (req.text response) "Hy mock"))))
```

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

### Example using mocket Python library as underlying mock engine

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

This example explicitly shows using the 'mocket' library as the underlying mock engine, potentially in conjunction with other libraries or frameworks that might not have direct Mocket integration.

```python
from mocket import Mocketizer
import requests

with Mocketizer() as m:
    m.register('http://underlying.com', content='Underlying mock engine')
    response = requests.get('http://underlying.com')
    assert response.text == 'Underlying mock engine'
```

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

### Activating Mock Engine via Decorator in Async Context

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Demonstrates activating the mock engine using a decorator within an asynchronous coroutine function. This enables mocking for asynchronous HTTP requests.

```python
import asyncio
from mocket import mocketize
import aiohttp

@mocketize
async def async_request():
    mocketize.register('http://async.com', content='Async response')
    async with aiohttp.ClientSession() as session:
        async with session.get('http://async.com') as response:
            return await response.text()

async def main():
    result = await async_request()
    assert result == 'Async response'

asyncio.run(main())
```

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

### Chainable API DSL Example

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Illustrates the use of Mocket's chainable Domain Specific Language (DSL) for defining mock requests and responses. This approach allows for a more fluent and readable way to configure mocks.

```python
from mocket import Mocketizer
import requests

with Mocketizer() as m:
    m.get('http://example.com').respond('Chainable response')
    response = requests.get('http://example.com')
    assert response.text == 'Chainable response'
```

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

### Activate Mock Engine with Decorator in Function Context (Python)

Source: https://pook.readthedocs.io/en/latest/examples

Shows how to activate Pook's mock engine using the `@pook.on` decorator within a standard Python function. It mocks a GET request to httpbin.org/ip with a custom response and verifies the response details.

```python
import requests

import pook


@pook.on
def run():
    pook.get(
        "httpbin.org/ip",
        reply=403,
        response_headers={"pepe": "lopez"},
        response_json={"error": "not found"},
    )

    res = requests.get("http://httpbin.org/ip")
    print("Status:", res.status_code)
    print("Headers:", res.headers)
    print("Body:", res.json())

    print("Is done:", pook.isdone())
    print("Pending mocks:", pook.pending_mocks())
    print("Unmatched requests:", pook.unmatched_requests())


run()
```

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

### Mock HTTP GET with aiohttp and async_timeout

Source: https://pook.readthedocs.io/en/latest/examples

This snippet demonstrates mocking a GET request to http://httpbin.org/ip using Pook with the aiohttp client and async_timeout for request duration. It sets up a mock reply with a 404 status code and custom headers, then executes the request and prints the response details. Dependencies include pook, aiohttp, asyncio, and async_timeout.

```python
import pook
import aiohttp
import asyncio
import async_timeout


async def fetch(session, url, data):
    with async_timeout.timeout(10):
        async with session.get(url, data=data) as res:
            print("Status:", res.status)
            print("Headers:", res.headers)
            print("Body:", await res.text())


with pook.use(network=True):
    pook.get(
        "http://httpbin.org/ip",
        reply=404,
        response_type="json",
        response_headers={"Server": "nginx"},
        response_json={"error": "not found"},
    )

    async def main(loop):
        async with aiohttp.ClientSession(loop=loop) as session:
            await fetch(session, "http://httpbin.org/ip", bytearray("foo bar", "utf-8"))

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))
```

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

### Enable Real Networking Mode

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Shows how to temporarily disable Mocket and enable real network requests. This is useful for testing scenarios where actual network communication is required.

```python
from mocket import Mocketizer

with Mocketizer(real_network=True):
    # Real network requests will be made here
    pass
```

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

### py.test Integration Example

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Illustrates integrating Mocket with the popular 'pytest' testing framework. This example shows how to use Mocket's decorators within pytest test functions.

```python
from mocket import mocketize
import requests

@mocketize
def test_pytest_mock():
    mocketize.register('http://pytest.com', content='Pytest mock')
    response = requests.get('http://pytest.com')
    assert response.text == 'Pytest mock'
```

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

### Using urllib3 to Return a Chunked Response

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Illustrates how to mock a 'urllib3' response that is delivered in chunks. This is useful for testing streaming data scenarios.

```python
from mocket import Mocketizer
import urllib3

with Mocketizer() as m:
    m.register('http://chunked.com', content='Chunked data', chunked=True)
    http = urllib3.PoolManager()
    response = http.request('GET', 'http://chunked.com', preload_content=False)
    # Process chunked response here
```

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

### Persistent Mock Example

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Demonstrates how to create persistent mocks that remain active across multiple test runs or application lifecycles. This is useful for caching or shared mock data.

```python
from mocket import Mocketizer

# Mocks registered here will persist
with Mocketizer() as m:
    m.register('http://persistent.com', content='Persistent data')

# The mock for http://persistent.com is still available
```

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

### Request Query Params Matching

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Illustrates matching requests based on their query parameters. This is essential for testing endpoints that use query strings to filter or modify requests.

```python
from mocket import Mocketizer
import requests

with Mocketizer() as m:
    m.register('http://query.com?id=123', content='Query matched')
    response = requests.get('http://query.com', params={'id': '123'})
    assert response.text == 'Query matched'
```

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

### Chainable API DSL for Mocking

Source: https://pook.readthedocs.io/en/latest/examples

This example showcases Pook's chainable API DSL for defining more complex mock configurations. It demonstrates how to chain methods to specify request body, content type, headers, reply status, and response headers/body for a POST request. The example uses `requests` to send the POST request and verifies the mocked response.

```python
import json

import requests

import pook

# Enable mock engine
pook.on()

(
    pook.post("httpbin.org/post")
    .json({"foo": "bar"})
    .type("json")
    .header("Client", "requests")
    .reply(201)
    .headers({"server": "pook"})
    .json({"error": "simulated"})
)

res = requests.post(
    "http://httpbin.org/post",
    data=json.dumps({"foo": "bar"}),
    headers={"Client": "requests", "Content-Type": "application/json"},
)

print("Status:", res.status_code)
print("Body:", res.json())

print("Is done:", pook.isdone())
print("Pending mocks:", pook.pending_mocks())

```

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

### Basic Mocking with Pook and Requests

Source: https://pook.readthedocs.io/en/latest/index_badge=latest

Demonstrates basic HTTP mocking using Pook's `get` method and verifying the response with the `requests` library. It shows how to set a reply status and JSON response, and assert the number of calls made to the mock.

```python
import pook
import requests

@pook.on
def test_my_api():
    mock = pook.get('http://twitter.com/api/1/foobar', reply=404, response_json={'error': 'not found'})

    resp = requests.get('http://twitter.com/api/1/foobar')
    assert resp.status_code == 404
    assert resp.json() == {"error": "not found"}
    assert mock.calls == 1

```

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

### Featured JSON Body Matching

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Shows how to match requests based on their JSON body content. This is useful for testing APIs that expect specific JSON payloads.

```python
from mocket import Mocketizer
import requests
import json

with Mocketizer() as m:
    payload = {'key': 'value'}
    m.register('http://json.match.com', content='JSON matched', method='POST', json=payload)
    response = requests.post('http://json.match.com', json=payload)
    assert response.text == 'JSON matched'
```

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

### Time TTL Limited Mock (Python)

Source: https://pook.readthedocs.io/en/latest/examples

Demonstrates how to limit a mock's usage to a specific number of times using `.times()`. This example sets up a mock that can be used twice before expiring.

```python
import requests

import pook

# Enable mock engine
pook.on()

# Declare mock
    pook.get("httpbin.org")
    .times(2)
    .reply(400)
    .headers({"server": "pook"})
    .json({"error": "simulated"})

# Mock request 1
res = requests.get("http://httpbin.org")
print("#1 status:", res.status_code)
print("#1 body:", res.json())

# Mock request 2
res = requests.get("http://httpbin.org")
print("#2 status:", res.status_code)
print("#2 body:", res.json())
```

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

### Single Mock Context Manager Definition

Source: https://pook.readthedocs.io/en/latest/examples

This example demonstrates defining a single mock within a context manager using `with pook.get(...) as mock:`. The mock is active only within this context and can be inspected for its status. After the context, the mock is no longer active, allowing for real network requests to be made. This is useful for precise control over mock lifecycles.

```python
import requests

import pook

# Define a new mock that will be only active within the context manager
with pook.get(
    "httpbin.org/ip",
    reply=403,
    response_headers={"pepe": "lopez"},
    response_json={"error": "not found"},
) as mock:
    res = requests.get("http://httpbin.org/ip")
    print("#1 Status:", res.status_code)
    print("#1 Headers:", res.headers)
    print("#1 Body:", res.json())
    print("----------------")

    res = requests.get("http://httpbin.org/ip")
    print("#2 Status:", res.status_code)
    print("#2 Headers:", res.headers)
    print("#2 Body:", res.json())
    print("----------------")

    print("Mock is done:", mock.isdone())
    print("Mock matches:", mock.total_matches)

    print("Is done:", pook.isdone())
    print("Pending mocks:", pook.pending_mocks())
    print("Unmatched requests:", pook.unmatched_requests())


# Explicitly disable mock engine
pook.off()

# Perform a real HTTP request since we are running the
# request outside of the context manager
res = requests.get("http://httpbin.org/ip")
print("#3 Status:", res.status_code)
print("#3 Headers:", res.headers)
print("#3 Body:", res.json())


```

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

### Simulated Error Exception on Mock Matching

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Shows how to configure a mock to raise a specific exception when matched. This is useful for testing error handling logic in your application.

```python
from mocket import Mocketizer
import requests

class CustomError(Exception):
    pass

with Mocketizer() as m:
    m.register('http://error.com', exc_class=CustomError, exc_args=('Simulated error',))
    try:
        requests.get('http://error.com')
    except CustomError as e:
        assert str(e) == 'Simulated error'
```

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

### Using Decorators for Mocking with Pook

Source: https://pook.readthedocs.io/en/latest/index_badge=latest

Shows how to use Pook decorators (`@pook.get`) to apply mocks directly to functions. This example demonstrates mocking multiple endpoints within a single function and verifying the status codes of the responses.

```python
import pook
import requests

@pook.get('http://httpbin.org/status/500', reply=204)
@pook.get('http://httpbin.org/status/400', reply=200)
def fetch(url):
    return requests.get(url)

res = fetch('http://httpbin.org/status/400')
print('#1 status:', res.status_code)

res = fetch('http://httpbin.org/status/500')
print('#2 status:', res.status_code)


```

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

### Registering HTTP Requests with Pook (GET, POST, PUT, PATCH, HEAD, DELETE, OPTIONS)

Source: https://pook.readthedocs.io/en/latest/api

These snippets demonstrate how to register mocks for various HTTP methods using Pook. Functions like `pook.get()`, `pook.post()`, `pook.put()`, `pook.patch()`, `pook.head()`, `pook.delete()`, and `pook.options()` allow you to specify the URL and other parameters for the mock.

```python
pook.get(_url_ , _** kw_)
pook.post(_url_ , _** kw_)
pook.put(_url_ , _** kw_)
pook.patch(_url =None_, _** kw_)
pook.head(_url_ , _** kw_)
pook.delete(_url_ , _** kw_)
pook.options(_url =None_, _** kw_)
```

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

### JSONSchema Based Body Matching

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Demonstrates matching requests based on a JSON Schema definition for the request body. This provides a more robust way to validate incoming JSON data.

```python
from mocket import Mocketizer
import requests

json_schema = {
    'type': 'object',
    'properties': {'name': {'type': 'string'}},
    'required': ['name']
}

with Mocketizer() as m:
    m.register('http://schema.com', content='Schema matched', json_schema=json_schema)
    response = requests.post('http://schema.com', json={'name': 'test'})
    assert response.text == 'Schema matched'
```

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

### Declaring Mocks as Decorators

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Explains how to use Mocket's decorator functionality to apply mocks to functions or methods. This allows for cleaner code by keeping mock definitions close to the code they affect.

```python
from mocket import mocketize
import requests

@mocketize
def fetch_data():
    mocketize.register('http://decorated.com', content='Decorated response')
    return requests.get('http://decorated.com').text

assert fetch_data() == 'Decorated response'
```

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

### Basic Request Mocking and Engine Control in Python

Source: https://pook.readthedocs.io/en/latest/examples

Demonstrates basic HTTP request mocking using Pook, including enabling/disabling the mock engine and checking mock status. It shows how to mock specific status codes and verify if mocks are done or pending.

```python
import requests
import pook

# Test function
res = pook.get("http://httpbin.org/status/400").reply(400)
res = fetch("http://httpbin.org/status/400")
print("#1 status:", res.status_code)

res = pook.get("http://httpbin.org/status/500").reply(500)
res = fetch("http://httpbin.org/status/500")
print("#2 status:", res.status_code)

print("Is done:", pook.isdone())
print("Pending mocks:", pook.pending_mocks())

# Disable mock engine
pook.off()

# Test real request
res = requests.get("http://httpbin.org/status/400")
print("Test status:", res.status_code)
```

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

### Context Manager for Isolated Mocking

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Shows how to use Mocket as a context manager to isolate mocking to a specific block of code. This ensures that mocks are only active within the 'with' statement, preventing unintended side effects.

```python
from mocket import Mocketizer
import requests

with Mocketizer() as m:
    m.register('http://isolated.com', content='Isolated mock')
    # Mocks are active here

# Mocks are not active here
```

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

### Enable Real Networking Mode with Pook (Python)

Source: https://pook.readthedocs.io/en/latest/examples

Demonstrates how to enable Pook's real networking mode, allowing actual HTTP requests to pass through when no mock matches. It shows enabling network mode, defining a mock, making a mocked request, and then a real request.

```python
import requests

import pook

# Enable mock engine
pook.on()

# Enable network mode
pook.enable_network()

    pook.get("httpbin.org/headers")
    .reply(201)
    .headers({"server": "pook"})
    .json({"error": "simulated"})

res = requests.get("http://httpbin.org/headers")
print("Mock status:", res.status_code)

# Real network request, since pook cannot match any mock
res = requests.get("http://httpbin.org/ip")
print("Real status:", res.status_code)

print("Is done:", pook.isdone())
print("Pending mocks:", pook.pending_mocks())

# Disable network mode once we're done
pook.disable_network()
```

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

### Time TTL Limited Mock

Source: https://pook.readthedocs.io/en/latest/_sources/examples.rst

Illustrates creating mocks with a Time-To-Live (TTL) expiration. After the specified duration, the mock will no longer be active, and real network requests may occur.

```python
from mocket import Mocketizer
import time

with Mocketizer() as m:
    m.register('http://ttl.com', content='TTL mock', ttl=1) # Expires in 1 second
    # Make a request within 1 second
    time.sleep(0.5)
    # Make a request after 1 second (mock will be expired)
```

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

### Mocking HTTP Requests with Pook in Hy (Lisp dialect)

Source: https://pook.readthedocs.io/en/latest/index_badge=latest

Provides an example of using Pook for HTTP mocking within the Hy programming language, a Lisp dialect for Python. It defines functions to set up mocks and make requests, demonstrating the use of `pook.use` as a context manager.

```hy
(import [pook])
(import [requests])

(defn request [url &optional [status 404]]
  (doto (.mock pook url) (.reply status))
  (let [res (.get requests url)]
    (. res status_code)))

(defn run []
  (with [(.use pook)]
    (print "Status:" (request "http://server.com/foo" :status 204))))

;; Run test program
(defmain [&args] (run))


```

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

### JSON Schema Based Body Matching (Python)

Source: https://pook.readthedocs.io/en/latest/examples

Demonstrates mocking requests based on a JSON schema for the request body. It defines a schema, sets up a mock using `.jsonschema()`, and sends a POST request to test the schema matching.

```python
import json

import requests

import pook

schema = {
    "type": "object",
    "properties": {
        "foo": {"type": "string"},
    },
}

# Enable mock engine
pook.on()

    pook.post("httpbin.org/post")
    .jsonschema(schema)
    .reply(201)
    .json({"error": "simulated"})

res = requests.post("http://httpbin.org/post", data=json.dumps({"foo": "bar"}))

print("Status:", res.status_code)
print("Body:", res.json())

print("Is done:", pook.isdone())
print("Pending mocks:", pook.pending_mocks())
```

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

### Mock HTTP GET with requests and mocket

Source: https://pook.readthedocs.io/en/latest/examples

This snippet demonstrates using Pook with the mocket library as the underlying mock engine to mock HTTP requests made with the requests library. It configures Pook to use MocketEngine, enables Pook, defines a mock for a Twitter API endpoint that expects two calls, makes the requests, and asserts the call count and response data. Ensure 'mocket' is installed (`pip install mocket`).

```python
# Be sure you have `mocket` installed:
# $ pip install mocket

import requests
from mocket.plugins.pook_mock_engine import MocketEngine

import pook

# Use mocket library as underlying mock engine
pook.set_mock_engine(MocketEngine)

# Explicitly enable pook HTTP mocking (required)
pook.on()

# Target server URL to mock out
url = "http://twitter.com/api/1/foobar"

# Define your mock
mock = pook.get(
    url,
    reply=404,
    times=2,
    headers={"content-type": "application/json"},
    response_json={"error": "foo"},
)

# Run first HTTP request
requests.get(url)
assert mock.calls == 1

# Run second HTTP request
res = requests.get(url)
assert mock.calls == 2

# Assert response data
assert res.status_code == 404
assert res.json() == {"error": "foo"}

# Explicitly disable pook (optional)
pook.off()
```

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

### Mock HTTP GET in Hy programming language

Source: https://pook.readthedocs.io/en/latest/examples

This example demonstrates mocking an HTTP GET request in the Hy programming language, which allows Python code to be written in Lisp syntax. It uses Pook to define a mock for a given URL with a specified status code and then uses the requests library to make the actual HTTP call, returning the status code of the response. The example is structured within a `run` function and executed using `defmain`.

```hy
(import [pook])
(import [requests])

(defn request [url &optional [status 404]]
  (doto (.mock pook url) (.reply status))
  (let [res (.get requests url)]
    (. res status_code)))

(defn run []
  (with [(.use pook)]
    (print "Status:" (request "http://foo.com/bar" :status 204))))

;; Run test program
(defmain [&args] (run))
```

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

### Declaring Mocks as Decorators

Source: https://pook.readthedocs.io/en/latest/examples

This example demonstrates how to declare Pook mocks using decorators directly on functions. Multiple mocks can be applied, and they will be active when the decorated function is called. This approach simplifies the setup for functions that consistently interact with specific mocked endpoints. The example uses `requests` within the decorated function.

```python
import requests

import pook


@pook.get("http://httpbin.org/status/500", reply=204)
@pook.get("http://httpbin.org/status/400", reply=200, persist=True)
def fetch(url):
    return requests.get(url)


```

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

### Mocking HTTP Requests with Regular Expressions in Python

Source: https://pook.readthedocs.io/en/latest/examples

This snippet demonstrates how to use Pook with regular expressions to match and mock HTTP requests. It mocks GET requests to URLs matching a pattern, with specific path and header requirements, and asserts the response status and JSON body. It requires the 'requests' and 'pook' libraries.

```python
import requests

import pook

# Enable mock engine
pook.on()

# Mock definition based
(pook.get(pook.regex("h[t]{2}pbin.*?"))
 .path(pook.regex("/foo/[a-z]+/baz"))
 .header("Client", pook.regex("requests|pook"))
 .times(2)
 .reply(200)
 .headers({"server": "pook"})
 .json({"foo": "bar"})
)

# Perform request
res = requests.get("http://httpbin.org/foo/bar/baz", headers={"Client": "requests"})
print("Status:", res.status_code)
print("Body:", res.json())

# Perform second request
res = requests.get("http://httpbin.org/foo/foo/baz", headers={"Client": "pook"})
print("Status:", res.status_code)
print("Body:", res.json())

print("Is done:", pook.isdone())
print("Pending mocks:", pook.pending_mocks())

```

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

### Simulating Errors with Pook in Python

Source: https://pook.readthedocs.io/en/latest/examples

This snippet demonstrates how to simulate an exception during an HTTP request using Pook. It mocks a GET request to a specific URL and configures it to raise a given exception upon matching. The code then attempts the request within a try-except block to catch and print the simulated error. It requires the 'requests' and 'pook' libraries.

```python
import requests

import pook

# Enable mock engine
pook.on()

# Simulated error exception on request matching
pook.get("httpbin.org/status/500", error=Exception("simulated error"))

try:
    requests.get("http://httpbin.org/status/500")
except Exception as err:
    print("Error:", err)

```

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

### Mocking Chunked Responses with Pook and urllib3 in Python

Source: https://pook.readthedocs.io/en/latest/examples

This snippet demonstrates how to mock a chunked HTTP response using Pook with the 'urllib3' library. Within a 'pook.use()' context, a GET request is mocked to return a 200 status with a body specified as a list of chunks. The code then makes the request and prints the received chunks. It requires 'urllib3' and 'pook'.

```python
import urllib3

import pook

# Mock HTTP traffic only in the given context
with pook.use():
    (pook.get("httpbin.org/chunky")
     .reply(200)
     .body(["returned", "as", "chunks"], chunked=True)
    )

    # Intercept request
    http = urllib3.PoolManager()
    r = http.request("GET", "httpbin.org/chunky")
    print("Chunks:", list(r.read_chunked()))

```

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

### Core API - options()

Source: https://pook.readthedocs.io/en/latest/api

A convenience method to set up a mock for an OPTIONS request. Equivalent to `on().options()`.

```APIDOC
## OPTIONS /api/data

### Description
Retrieves the allowed HTTP methods for the /api/data endpoint.

### Method
OPTIONS

### Endpoint
/api/data

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(No request body for OPTIONS requests)

### Request Example
(No request body for OPTIONS requests)

### Response
#### Success Response (200)
- **Allow** (string) - A comma-separated list of allowed HTTP methods (e.g., 'GET, POST, PUT').

#### Response Example
(Response headers only, including 'Allow' header)
```

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

### Core API - post()

Source: https://pook.readthedocs.io/en/latest/api

A convenience method to set up a mock for a POST request. Equivalent to `on().post()`.

```APIDOC
## POST /api/logs

### Description
Adds a new log entry to the system.

### Method
POST

### Endpoint
/api/logs

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
- **message** (string) - Required - The log message content.
- **level** (string) - Optional - The severity level of the log (e.g., 'info', 'warn', 'error'). Defaults to 'info'.

### Request Example
```json
{
  "message": "User logged in successfully.",
  "level": "info"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the newly created log entry.
- **timestamp** (string) - The timestamp when the log was created.

#### Response Example
```json
{
  "id": "log-abc123",
  "timestamp": "2023-10-27T10:00:00Z"
}
```
```

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

### Pook with Mocket Engine for Mocking

Source: https://pook.readthedocs.io/en/latest/index_badge=latest

Demonstrates using Pook with the `mocket` Python library as the underlying mock engine. This involves setting the mock engine using `pook.set_mock_engine` and then defining mocks as usual. It shows mocking a request with specific headers and JSON response, and verifying call counts.

```python
import pook
import requests
from mocket.plugins.pook_mock_engine import MocketEngine

# Use mocket library as underlying mock engine
pook.set_mock_engine(MocketEngine)

# Explicitly enable pook HTTP mocking (optional)
pook.on()

# Target server URL to mock out
url = 'http://twitter.com/api/1/foobar'

# Define your mock
mock = pook.get(url,
                reply=404, times=2,
                headers={'content-type': 'application/json'},
                response_json={'error': 'foo'})

# Run first HTTP request
requests.get(url)
assert mock.calls == 1

# Run second HTTP request
res = requests.get(url)
assert mock.calls == 2

# Assert response data
assert res.status_code == 404
assert res.json() == {'error': 'foo'}

# Explicitly disable pook (optional)
pook.off()


```

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

### Add and Get Pook Interceptors

Source: https://pook.readthedocs.io/en/latest/api

Functions for registering custom interceptors and retrieving existing interceptors by name. `add` allows registering one or more custom interceptor instances, while `get` retrieves an interceptor instance based on its class name or alias.

```python
from pook.interceptors import MyCustomInterceptor

pook.interceptors.add(MyCustomInterceptor())

interceptor = pook.interceptors.get("MyCustomInterceptor")
```

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

### Using Pook as a Context Manager for Mocking

Source: https://pook.readthedocs.io/en/latest/api

This snippet shows how to use Pook's `use()` and `use_network()` as context managers to create isolated mock engines. Within the `with` block, requests to 'server.com/foo' are mocked to return a 404 status code, which is then asserted.

```python
with pook.use() as engine:
    pook.mock('server.com/foo').reply(404)

    res = requests.get('server.com/foo')
    assert res.status_code == 404

with pook.use_network() as engine:
    pook.mock('server.com/foo').reply(404)

    res = requests.get('server.com/foo')
    assert res.status_code == 404
```

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

### Interceptors API - get()

Source: https://pook.readthedocs.io/en/latest/api

Retrieves a list of all currently active interceptors in Pook.

```APIDOC
## GET /api/interceptors

### Description
Retrieves a list of all currently active interceptors registered with Pook.

### Method
GET

### Endpoint
/api/interceptors

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(No request body for GET requests)

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **interceptors** (array) - A list of objects, where each object represents an active interceptor and its details.
  - **type** (string) - The type of the interceptor.
  - **name** (string) - The name of the interceptor.

#### Response Example
```json
{
  "interceptors": [
    {
      "type": "aiohttp",
      "name": "aiohttp-interceptor-1"
    },
    {
      "type": "httpx",
      "name": "httpx-interceptor-1"
    }
  ]
}
```
```

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

### Core API - head()

Source: https://pook.readthedocs.io/en/latest/api

A convenience method to set up a mock for a HEAD request. Equivalent to `on().head()`.

```APIDOC
## HEAD /api/resource/{resourceId}

### Description
Retrieves the headers for a specific resource without fetching the entire content.

### Method
HEAD

### Endpoint
/api/resource/{resourceId}

### Parameters
#### Path Parameters
- **resourceId** (string) - Required - The ID of the resource.

#### Query Parameters
(None)

#### Request Body
(No request body for HEAD requests)

### Request Example
(No request body for HEAD requests)

### Response
#### Success Response (200)
Headers related to the resource (e.g., Content-Type, Content-Length).

#### Response Example
(Response headers only, no body)
```

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

### Core API - on()

Source: https://pook.readthedocs.io/en/latest/api

Sets up a mock for a specific HTTP request. This is a fundamental function for defining how Pook should intercept and respond to requests.

```APIDOC
## GET /api/items/{itemId}

### Description
Retrieves a specific item by its ID. This endpoint allows fetching detailed information about a single item.

### Method
GET

### Endpoint
/api/items/{itemId}

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The unique identifier of the item to retrieve.

#### Query Parameters
- **fields** (string) - Optional - A comma-separated list of fields to include in the response.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the item.
- **name** (string) - The name of the item.
- **description** (string) - A description of the item.

#### Response Example
```json
{
  "id": "item-123",
  "name": "Example Item",
  "description": "This is a sample item description."
}
```
```

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

### Request Class Initialization and Property Management (Python)

Source: https://pook.readthedocs.io/en/latest/_modules/pook/request

This snippet details the `__init__` method and property setters for the `Request` class. It shows how the constructor initializes various attributes like method, URL, headers, and body, and how the setters handle type checking and data transformation (e.g., encoding body to bytes, parsing query strings, and handling URL parsing).

```python
from pook.request import Request
from urllib.parse import urlparse

# Initialize with default method and keyword arguments
req = Request(method="PUT", url="http://localhost:8080/items/1", body=b"updated content")

# Setting properties
req.headers = {"Authorization": "Bearer token"}
req.query = "user_id=123&status=active"

# Accessing properties
print(req.method)       # Output: PUT
print(req.rawurl)       # Output: http://localhost:8080/items/1
print(req.headers)      # Output: {'Authorization': 'Bearer token'}
print(req.query)        # Output: {'user_id': ['123'], 'status': ['active']}
print(req.body)         # Output: b'updated content'

# Setting JSON body
req.json = {"status": "completed"}
print(req.body)         # Output: b'{"status": "completed"}'
print(req.json)         # Output: {'status': 'completed'}
```

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

### Isolated Mocking with Context Manager

Source: https://pook.readthedocs.io/en/latest/examples

This example illustrates how to use Pook's context manager (`pook.api.context()`) for isolated mocking. Mocks defined within the `with` block are only active during that block, ensuring they don't affect subsequent code. This is useful for testing specific scenarios without global side effects. It uses the `requests` library to make the mocked request.

```python
import requests

import pook

with pook.api.context():
    pook.get(
        "httpbin.org/ip",
        reply=403,
        response_headers={"pepe": "lopez"},
        response_json={"error": "not found"},
    )

    res = requests.get("http://httpbin.org/ip")
    print("Status:", res.status_code)
    print("Headers:", res.headers)
    print("Body:", res.json())

    print("Is done:", pook.isdone())
    print("Pending mocks:", pook.pending_mocks())
    print("Unmatched requests:", pook.unmatched_requests())


```

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

### Get Unmatched Intercepted Requests (Python)

Source: https://pook.readthedocs.io/en/latest/_modules/pook/api

Retrieves a list of all requests that were intercepted but did not match any registered mocks. This functionality requires the 'networking' mode to be enabled.

```python
import pook

# Assuming pook is configured and networking mode is enabled
# unmatched_requests = pook.unmatched_requests()
# print(unmatched_requests)
```

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

### Get Current Mock Engine

Source: https://pook.readthedocs.io/en/latest/_modules/pook/api

Returns the currently active mock engine instance. This allows direct interaction with the engine's functionalities if needed.

```python
def engine():
    """
    Returns the current running mock engine.

    Returns:
        pook.Engine: current used engine.
    """
    return _engine
```

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

### Enable Pook Interceptors with pook.on() (Python)

Source: https://pook.readthedocs.io/en/latest/api

Shows the usage of the `pook.on()` function, which is an alias for `pook.activate()`, to enable HTTP traffic interceptors. It includes setting up a mock and verifying a request.

```python
import pook
import requests

# Standard usage
pook.on()
pook.mock('server.com/foo').reply(404)

res = requests.get('server.com/foo')
assert res.status_code == 404
```
Tokens:
Raw