zope.dottedname

7.1 · active · verified Thu Apr 16

zope.dottedname is a Python library that provides a single `resolve()` function for converting strings containing Python dotted names (e.g., 'os.path.join') into the corresponding Python object (module, class, function, etc.). It is currently at version 7.1 and is actively maintained by the Zope Foundation, with several releases per year to add new Python version support and address maintenance.

Common errors

```
ImportError: No module named 'some_nonexistent_module' (or similar for top-level imports)
```
cause The `resolve()` function could not find the specified module at the root of the Python path.

fix Double-check the spelling of the module name. Ensure the module is installed and accessible in your Python environment. If it's a sub-module, verify the full dotted path (e.g., 'package.submodule').
```
AttributeError: module 'some_module' has no attribute 'nonexistent_attribute'
```
cause The module specified in the dotted name was found, but the subsequent attribute (class, function, variable) does not exist within that module.

fix Verify the spelling of the attribute. Confirm that the attribute is indeed exposed by the module and that you are using the correct full dotted path to it.
```
ValueError: relative name '..some_name' requires a 'relative_to' argument
```
cause You attempted to resolve a relative dotted name (e.g., `'.some_name'` or `'..some_name'`) without providing the necessary `relative_to` argument.

fix When resolving relative dotted names, always specify the `relative_to` argument with the full dotted name of the module or package against which the relative path should be resolved. For example: `resolve('.some_function', relative_to='my_package.my_module')`.

Warnings

breaking Version 7.0 (2025-09-12) replaced the `pkg_resources` namespace with PEP 420 native namespace. Projects relying on older `pkg_resources` based namespace package discovery might experience issues.
Fix: Ensure your project fully supports PEP 420 namespace packages and update any custom tooling that might still depend on `pkg_resources` for namespace resolution.
breaking Zope libraries, including `zope.dottedname`, frequently drop support for older Python versions with new major releases. For example, v7.1 dropped Python 3.9, v6.1 dropped Python 3.7 and 3.8, and v6.0 dropped Python 3.6.
Fix: Always check the `requires_python` metadata on PyPI or the project's documentation when upgrading `zope.dottedname` to ensure compatibility with your Python environment. Update to a supported Python version if necessary.
gotcha When resolving relative dotted names, the `relative_to` argument must be provided. Failing to do so for a relative name will result in a `ValueError`.
Fix: For relative dotted names (e.g., starting with a dot), always supply the `relative_to` argument, which should be the dotted name of the module or package from which the relative import is intended.

Install

pip install zope.dottedname Install stable version

Imports

resolve
```
from zope.dottedname import resolve
```
The primary and typically only function needed from this library.

Quickstart

The `resolve` function is the core of `zope.dottedname`. It takes a dotted name string and returns the corresponding Python object. It can handle both absolute and relative dotted names, with relative names requiring an additional `relative_to` argument.

from zope.dottedname import resolve

# Resolve an absolute dotted name to a module
math_module = resolve('math')
print(f"Resolved 'math' to: {math_module}")

# Resolve an absolute dotted name to a function within a module
join_function = resolve('os.path.join')
print(f"Resolved 'os.path.join' to: {join_function}")

# Resolve a relative dotted name (e.g., '.split' relative to 'os.path')
split_function = resolve('.split', relative_to='os.path')
print(f"Resolved '.split' relative to 'os.path' to: {split_function}")

# Resolve a relative dotted name across package boundaries ('..system' relative to 'os.path')
system_function = resolve('..system', relative_to='os.path')
print(f"Resolved '..system' relative to 'os.path' to: {system_function}")

view raw JSON →