Module couchdb3.utils

Global variables

var COUCHDB_GLOBAL_CHANGES_DB_NAME : str

Reserved CouchDB global changes database name.

var COUCHDB_REPLICATOR_DB_NAME : str

Reserved CouchDB replicator database name.

var COUCHDB_USERS_DB_NAME : str

Reserved CouchDB users database name.

var COUCH_DB_RESERVED_DB_NAMES : set[str]

Reserved CouchDB database names.

var COUCH_DB_RESERVED_DOC_FIELDS : set[str]

Reserved CouchDB document fields.

var DEFAULT_AUTH_METHOD : str

The default authentication method - values to "cookie".

var DEFAULT_TIMEOUT : int

The default timeout set in requests - values to 300.

var PATTERN_DB_NAME : re.Pattern

The pattern for valid database names.

var PATTERN_USER_ID : re.Pattern

The pattern for valid user IDs.

var VALID_AUTH_METHODS : set[str]

The valid auth method arguments. Possible values are "basic" or "cookie".

var VALID_SCHEMES : set[str]

The valid TCP schemes. Possible values are "http" or "https" or "socks5".

Functions

def basic_auth(user: str, password: str) ‑> str
Expand source code 
def basic_auth(user: str, password: str) -> str:
    """
    Create basic authentication headers value.

    Parameters
    ----------
    user : str
        A CouchDB user name.
    password : str
        A corresponding CouchDB user password.

    Returns
    -------
    str : The credentials concatenated with a colon and base64 encoded.
    """
    return base64.b64encode(f"{user}:{password}".encode()).decode()

Create basic authentication headers value.

Parameters

user : str
A CouchDB user name.
password : str
A corresponding CouchDB user password.

Returns

str : The credentials concatenated with a colon and base64 encoded.

def build_query(**kwargs) ‑> str | None
Expand source code 
def build_query(
    **kwargs,
) -> str | None:
    """

    Parameters
    ----------
    kwargs
        Arbitrary keyword-args to be passed as query-params in a URL.
    Returns
    -------
    str : A string containing the keyword-args encoded as URL query-params.
    """
    return parse.urlencode({key: _handler(val) for key, val in kwargs.items() if val is not None})

Parameters

kwargs
Arbitrary keyword-args to be passed as query-params in a URL.

Returns

str : A string containing the keyword-args encoded as URL query-params.

def build_url(*, scheme: str, host: str, path: str | None = None, port: int | None = None, **kwargs) ‑> str
Expand source code 
def build_url(
    *,
    scheme: str,
    host: str,
    path: str | None = None,
    port: int | None = None,
    **kwargs,
) -> str:
    """
    Build a URL using the provided scheme, host, path & kwargs.

    Parameters
    ----------
    scheme : str
        The URL scheme (e.g `http`).
    host : str
        The URL host (e.g. `example.com`).
    path : str
        The URL path (e.g. `/api/data`). Default `None`.
    port : int
        The port to connect to (e.g. `5984`). Default `None`.
    kwargs
        Arbitrary keyword-args to be passed as query-params in a URL.
    Returns
    -------
    str : The fully constructed URL string.
    """
    host_part = f"{host}:{port}" if port else host
    base = f"{scheme}://{host_part}"
    if path:
        base += f"/{path.lstrip('/')}"
    query = build_query(**kwargs)
    if query:
        base += f"?{query}"
    return base

Build a URL using the provided scheme, host, path & kwargs.

Parameters

scheme : str
The URL scheme (e.g http).
host : str
The URL host (e.g. example.com).
path : str
The URL path (e.g. /api/data). Default None.
port : int
The port to connect to (e.g. 5984). Default None.
kwargs
Arbitrary keyword-args to be passed as query-params in a URL.

Returns

str : The fully constructed URL string.

def check_response(response: httpx.Response) ‑> None
Expand source code 
def check_response(response: httpx.Response) -> None:
    """
    Check if a request yields a successful response.

    Parameters
    ----------
    response : httpx.Response
        An `httpx.Response` object.
    Returns
    -------
    None
    Raises
    ------
    One of the following exceptions:

    - couchdb3.error.CouchDBError
    - ConnectionError
    - TimeoutError
    - httpx.ConnectError
    - httpx.HTTPStatusError

    """
    try:
        response.raise_for_status()
    except (
        ConnectionError,
        TimeoutError,
        httpx.ConnectError,
        httpx.HTTPStatusError,
    ):
        if response.status_code in exceptions.STATUS_CODE_ERROR_MAPPING:
            _ = exceptions.STATUS_CODE_ERROR_MAPPING[response.status_code]
            if _:
                raise _(response.text)
            else:
                return
        raise

Check if a request yields a successful response.

Parameters

response : httpx.Response
An httpx.Response object.

Returns

None
 

Raises

One of the following exceptions:
 
  • couchdb3.error.CouchDBError
  • ConnectionError
  • TimeoutError
  • httpx.ConnectError
  • httpx.HTTPStatusError
def extract_url_data(url: str) ‑> dict
Expand source code 
def extract_url_data(url: str) -> dict:
    """
    Extract scheme, credentials, host, port & path from a URL.

    Parameters
    ----------
    url : str
        A URL string.

    Returns
    -------
    Dict : A dictionary containing with the following items.

      - scheme
      - user
      - password
      - host
      - port
      - path
    """
    if not any(url.startswith(_) for _ in VALID_SCHEMES):
        url = f"http://{url}"
    parsed = urlparse(url)
    return {
        "scheme": parsed.scheme,
        "user": parsed.username or None,
        "password": parsed.password or None,
        "host": parsed.hostname,
        "port": parsed.port,
        "path": parsed.path or None,
    }

Extract scheme, credentials, host, port & path from a URL.

Parameters

url : str
A URL string.

Returns

Dict : A dictionary containing with the following items.

  • scheme
  • user
  • password
  • host
  • port
  • path
def partitioned_db_resource_parser(resource: str | None = None, partition: str | None = None) ‑> str | None
Expand source code 
def partitioned_db_resource_parser(
    resource: str | None = None,
    partition: str | None = None,
) -> str | None:
    """
    Build resource path with optional partition ID.

    Parameters
    ----------
    resource : str
        The resource to fetch (relative to the host). Default `None`.
    partition: str
        An optional partition ID. Only valid for partitioned databases. (Default `None`.)
    Returns
    ----------
        The (relative) path of the resource.
    """
    return f"_partition/{partition}/{resource}" if partition else resource

Build resource path with optional partition ID.

Parameters

resource : str
The resource to fetch (relative to the host). Default None.
partition : str
An optional partition ID. Only valid for partitioned databases. (Default None.)

Returns

The (relative) path of the resource.
def rm_nones_from_dict(data: dict, /) ‑> dict
Expand source code 
def rm_nones_from_dict(data: dict, /) -> dict:
    """
    Removes all `None` keys from a dictionary.

    Parameters
    ----------
    data : dict
        A dictionary.

    Returns
    -------
    dict : A dictionary without `None` keys.
    """
    return {k: v for k, v in data.items() if v is not None}

Removes all None keys from a dictionary.

Parameters

data : dict
A dictionary.

Returns

dict : A dictionary without None keys.

def user_name_to_id(name: str) ‑> str
Expand source code 
def user_name_to_id(name: str) -> str:
    """
    Convert a name into a valid CouchDB user ID.

    Parameters
    ----------
    name : str
        A user name.

    Returns
    -------
    str : A valid CouchDB ID, i.e. of the form `org.couchdb.user:{name}`.
    """
    return f"org.couchdb.user:{name}"

Convert a name into a valid CouchDB user ID.

Parameters

name : str
A user name.

Returns

str : A valid CouchDB ID, i.e. of the form org.couchdb.user:{name}.

def validate_auth_method(auth_method: str) ‑> bool
Expand source code 
def validate_auth_method(auth_method: str) -> bool:
    """
    Checks if the provided authentication method is valid.

    Parameters
    ----------
    auth_method : str

    Returns
    -------
    bool: `True` if `auth_method` is in `VALID_AUTH_METHODS`.
    """
    return auth_method in VALID_AUTH_METHODS

Checks if the provided authentication method is valid.

Parameters

auth_method : str
 

Returns

bool: True if auth_method is in VALID_AUTH_METHODS.

def validate_db_name(name: str) ‑> bool
Expand source code 
def validate_db_name(name: str) -> bool:
    """
    Checks a name for CouchDB name-compliance.

    Parameters
    ----------
    name : str
        A prospective database name.

    Returns
    -------
    bool : `True` if the provided name is CouchDB compliant.
    """
    return name in COUCH_DB_RESERVED_DB_NAMES or bool(PATTERN_DB_NAME.fullmatch(name))

Checks a name for CouchDB name-compliance.

Parameters

name : str
A prospective database name.

Returns

bool : True if the provided name is CouchDB compliant.

def validate_proxy(proxy: str) ‑> bool
Expand source code 
def validate_proxy(proxy: str) -> bool:
    """
    Check a proxy scheme for CouchDB proxy-scheme-compliance

    Parameters
    ----------
    proxy : str
        A prospective proxy.

    Returns
    -------
    bool : `True` if the provided proxy is CouchDB compliant.
    """
    return urlparse(proxy).scheme in VALID_SCHEMES

Check a proxy scheme for CouchDB proxy-scheme-compliance

Parameters

proxy : str
A prospective proxy.

Returns

bool : True if the provided proxy is CouchDB compliant.

def validate_user_id(user_id: str) ‑> bool
Expand source code 
def validate_user_id(user_id: str) -> bool:
    """
    Checks a user ID for CouchDB user-id-compliance.

    Parameters
    ----------
    user_id : str
        A prospective user ID.

    Returns
    -------
    bool : `True` if the provided user ID is CouchDB compliant.

    """
    return bool(PATTERN_USER_ID.fullmatch(user_id))

Checks a user ID for CouchDB user-id-compliance.

Parameters

user_id : str
A prospective user ID.

Returns

bool : True if the provided user ID is CouchDB compliant.

Classes

class MimeTypeEnum (*values)

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

  • attribute access:

Color.RED

  • value lookup:

Color(1)

  • name lookup:

Color['RED']

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

  • enum.Enum

Class variables

var mime_type_3g2

The type of the None singleton.

var mime_type_3gp

The type of the None singleton.

var mime_type_3gpp

The type of the None singleton.

var mime_type_3gpp2

The type of the None singleton.

var mime_type_7z

The type of the None singleton.

var mime_type_a

The type of the None singleton.

var mime_type_aac

The type of the None singleton.

var mime_type_adts

The type of the None singleton.

var mime_type_ai

The type of the None singleton.

var mime_type_aif

The type of the None singleton.

var mime_type_aifc

The type of the None singleton.

var mime_type_aiff

The type of the None singleton.

var mime_type_ass

The type of the None singleton.

var mime_type_au

The type of the None singleton.

var mime_type_avi

The type of the None singleton.

var mime_type_avif

The type of the None singleton.

var mime_type_bat

The type of the None singleton.

var mime_type_bcpio

The type of the None singleton.

var mime_type_bin

The type of the None singleton.

var mime_type_bmp

The type of the None singleton.

var mime_type_c

The type of the None singleton.

var mime_type_cdf

The type of the None singleton.

var mime_type_cpio

The type of the None singleton.

var mime_type_csh

The type of the None singleton.

var mime_type_css

The type of the None singleton.

var mime_type_csv

The type of the None singleton.

var mime_type_deb

The type of the None singleton.

var mime_type_dll

The type of the None singleton.

var mime_type_doc

The type of the None singleton.

var mime_type_docx

The type of the None singleton.

var mime_type_dot

The type of the None singleton.

var mime_type_dvi

The type of the None singleton.

var mime_type_emf

The type of the None singleton.

var mime_type_eml

The type of the None singleton.

var mime_type_eot

The type of the None singleton.

var mime_type_eps

The type of the None singleton.

var mime_type_epub

The type of the None singleton.

var mime_type_etx

The type of the None singleton.

var mime_type_exe

The type of the None singleton.

var mime_type_fits

The type of the None singleton.

var mime_type_flac

The type of the None singleton.

var mime_type_g3

The type of the None singleton.

var mime_type_gif

The type of the None singleton.

var mime_type_glb

The type of the None singleton.

var mime_type_gltf

The type of the None singleton.

var mime_type_gtar

The type of the None singleton.

var mime_type_gz

The type of the None singleton.

var mime_type_h

The type of the None singleton.

var mime_type_h5

The type of the None singleton.

var mime_type_hdf

The type of the None singleton.

var mime_type_heic

The type of the None singleton.

var mime_type_heif

The type of the None singleton.

var mime_type_htm

The type of the None singleton.

var mime_type_html

The type of the None singleton.

var mime_type_ico

The type of the None singleton.

var mime_type_ief

The type of the None singleton.

var mime_type_jp2

The type of the None singleton.

var mime_type_jpe

The type of the None singleton.

var mime_type_jpeg

The type of the None singleton.

var mime_type_jpg

The type of the None singleton.

var mime_type_jpm

The type of the None singleton.

var mime_type_jpx

The type of the None singleton.

var mime_type_js

The type of the None singleton.

var mime_type_json

The type of the None singleton.

var mime_type_ksh

The type of the None singleton.

var mime_type_latex

The type of the None singleton.

var mime_type_loas

The type of the None singleton.

var mime_type_m1v

The type of the None singleton.

var mime_type_m3u

The type of the None singleton.

var mime_type_m3u8

The type of the None singleton.

var mime_type_m4a

The type of the None singleton.

var mime_type_m4v

The type of the None singleton.

var mime_type_man

The type of the None singleton.

var mime_type_markdown

The type of the None singleton.

var mime_type_md

The type of the None singleton.

var mime_type_me

The type of the None singleton.

var mime_type_mht

The type of the None singleton.

var mime_type_mhtml

The type of the None singleton.

var mime_type_mif

The type of the None singleton.

var mime_type_mjs

The type of the None singleton.

var mime_type_mk3d

The type of the None singleton.

var mime_type_mka

The type of the None singleton.

var mime_type_mkv

The type of the None singleton.

var mime_type_mov

The type of the None singleton.

var mime_type_movie

The type of the None singleton.

var mime_type_mp2

The type of the None singleton.

var mime_type_mp3

The type of the None singleton.

var mime_type_mp4

The type of the None singleton.

var mime_type_mpa

The type of the None singleton.

var mime_type_mpe

The type of the None singleton.

var mime_type_mpeg

The type of the None singleton.

var mime_type_mpg

The type of the None singleton.

var mime_type_ms

The type of the None singleton.

var mime_type_n3

The type of the None singleton.

var mime_type_nc

The type of the None singleton.

var mime_type_nq

The type of the None singleton.

var mime_type_nt

The type of the None singleton.

var mime_type_nws

The type of the None singleton.

var mime_type_o

The type of the None singleton.

var mime_type_obj

The type of the None singleton.

var mime_type_oda

The type of the None singleton.

var mime_type_odg

The type of the None singleton.

var mime_type_odp

The type of the None singleton.

var mime_type_ods

The type of the None singleton.

var mime_type_odt

The type of the None singleton.

var mime_type_ogg

The type of the None singleton.

var mime_type_ogv

The type of the None singleton.

var mime_type_ogx

The type of the None singleton.

var mime_type_opus

The type of the None singleton.

var mime_type_otf

The type of the None singleton.

var mime_type_p12

The type of the None singleton.

var mime_type_p7c

The type of the None singleton.

var mime_type_pbm

The type of the None singleton.

var mime_type_pdf

The type of the None singleton.

var mime_type_pfx

The type of the None singleton.

var mime_type_pgm

The type of the None singleton.

var mime_type_php

The type of the None singleton.

var mime_type_pl

The type of the None singleton.

var mime_type_png

The type of the None singleton.

var mime_type_pnm

The type of the None singleton.

var mime_type_pot

The type of the None singleton.

var mime_type_ppa

The type of the None singleton.

var mime_type_ppm

The type of the None singleton.

var mime_type_pps

The type of the None singleton.

var mime_type_ppt

The type of the None singleton.

var mime_type_pptx

The type of the None singleton.

var mime_type_ps

The type of the None singleton.

var mime_type_pwz

The type of the None singleton.

var mime_type_py

The type of the None singleton.

var mime_type_pyc

The type of the None singleton.

var mime_type_pyo

The type of the None singleton.

var mime_type_qt

The type of the None singleton.

var mime_type_ra

The type of the None singleton.

var mime_type_ram

The type of the None singleton.

var mime_type_rar

The type of the None singleton.

var mime_type_ras

The type of the None singleton.

var mime_type_rdf

The type of the None singleton.

var mime_type_rgb

The type of the None singleton.

var mime_type_roff

The type of the None singleton.

var mime_type_rpm

The type of the None singleton.

var mime_type_rst

The type of the None singleton.

var mime_type_rtf

The type of the None singleton.

var mime_type_rtx

The type of the None singleton.

var mime_type_sgm

The type of the None singleton.

var mime_type_sgml

The type of the None singleton.

var mime_type_sh

The type of the None singleton.

var mime_type_shar

The type of the None singleton.

var mime_type_snd

The type of the None singleton.

var mime_type_so

The type of the None singleton.

var mime_type_src

The type of the None singleton.

var mime_type_srt

The type of the None singleton.

var mime_type_stl

The type of the None singleton.

var mime_type_sv4cpio

The type of the None singleton.

var mime_type_sv4crc

The type of the None singleton.

var mime_type_svg

The type of the None singleton.

var mime_type_swf

The type of the None singleton.

var mime_type_t

The type of the None singleton.

var mime_type_t38

The type of the None singleton.

var mime_type_tar

The type of the None singleton.

var mime_type_tcl

The type of the None singleton.

var mime_type_tex

The type of the None singleton.

var mime_type_texi

The type of the None singleton.

var mime_type_texinfo

The type of the None singleton.

var mime_type_tfx

The type of the None singleton.

var mime_type_tif

The type of the None singleton.

var mime_type_tiff

The type of the None singleton.

var mime_type_tr

The type of the None singleton.

var mime_type_trig

The type of the None singleton.

var mime_type_tsv

The type of the None singleton.

var mime_type_ttf

The type of the None singleton.

var mime_type_txt

The type of the None singleton.

var mime_type_ustar

The type of the None singleton.

var mime_type_vcf

The type of the None singleton.

var mime_type_vtt

The type of the None singleton.

var mime_type_wasm

The type of the None singleton.

var mime_type_wav

The type of the None singleton.

var mime_type_weba

The type of the None singleton.

var mime_type_webm

The type of the None singleton.

var mime_type_webmanifest

The type of the None singleton.

var mime_type_webp

The type of the None singleton.

var mime_type_wiz

The type of the None singleton.

var mime_type_wmf

The type of the None singleton.

var mime_type_wmv

The type of the None singleton.

var mime_type_woff

The type of the None singleton.

var mime_type_woff2

The type of the None singleton.

var mime_type_wsdl

The type of the None singleton.

var mime_type_xbm

The type of the None singleton.

var mime_type_xlb

The type of the None singleton.

var mime_type_xls

The type of the None singleton.

var mime_type_xlsx

The type of the None singleton.

var mime_type_xml

The type of the None singleton.

var mime_type_xpdl

The type of the None singleton.

var mime_type_xpm

The type of the None singleton.

var mime_type_xsl

The type of the None singleton.

var mime_type_xwd

The type of the None singleton.

var mime_type_yaml

The type of the None singleton.

var mime_type_yml

The type of the None singleton.

var mime_type_zip

The type of the None singleton.