dissolve

The dissolve library helps users replace calls to deprecated library APIs by
automatically substituting the deprecated function call with the body of the
deprecated function.

Installation

Basic installation (for using the @replace_me decorator):

$ pip install dissolve

This provides the @replace_me decorator for marking deprecated functions and generating
deprecation warnings with replacement suggestions.

For the dissolve command-line tool, first install the Python package:

$ pip install dissolve

Then install the high-performance Rust binary:

$ cargo install dissolve-python

If you don't have Rust installed:

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ source ~/.cargo/env
$ cargo install dissolve-python

The Python package provides a wrapper that automatically detects and uses the Rust binary when available.

The CLI provides the following commands:

dissolve migrate: Automatically replace deprecated function calls
dissolve cleanup: Remove deprecated functions after migration
dissolve check: Validate that deprecations can be migrated
dissolve info: List all deprecated functions and their replacements

Example

E.g. if you had a function "inc" that has been renamed to "increment" in
version 0.1.0 of your library:

from dissolve import replace_me

def increment(x):
    return x + 1

@replace_me(since="0.1.0")
def inc(x):
    return increment(x)

Running this code will yield a warning:

...
>>> inc(x=3)
<stdin>:1: DeprecationWarning: <function inc at 0x7feaf5ead5a0> has been deprecated since 0.1.0; use 'increment(x)' instead
4

Running the dissolve migrate command will automatically replace the
deprecated function call with the suggested replacement:

$ dissolve migrate --write myproject/utils.py
Modified: myproject/utils.py
...
result = increment(x=3)
...

For library users: The migration step above is typically all you need.
Your code now uses the new increment function instead of the deprecated inc function.

For library maintainers: After users have had time to migrate and you're ready
to remove the deprecated function from your library, you can use dissolve cleanup:

$ dissolve cleanup --all --write myproject/utils.py
Modified: myproject/utils.py

This removes the inc function entirely from the library, leaving only the increment function.

dissolve migrate

The dissolve migrate command can automatically update your codebase to
replace deprecated function calls with their suggested replacements.

Usage:

$ dissolve migrate path/to/code

This will:

Search for Python files in the specified path
Find calls to functions decorated with @replace_me
Replace them with the suggested replacement expression
Show a diff of the changes

Options:

-w, --write: Write changes back to files instead of printing to stdout
--check: Check if files need migration without modifying them (exits with code 1 if changes are needed)

Examples:

Preview changes:

$ dissolve migrate myproject/utils.py
# Migrated: myproject/utils.py
...
result = 5 + 1
...

Check if migration is needed:

$ dissolve migrate --check myproject/
myproject/utils.py: needs migration
myproject/core.py: up to date
$ echo $?
1

Apply changes:

$ dissolve migrate --write myproject/
Modified: myproject/utils.py
Unchanged: myproject/core.py

The command respects the replacement expressions defined in the @replace_me
decorator and substitutes actual argument values.

How dissolve Works

Dissolve uses type inference to determine which function calls to migrate. This
avoids false positives when different classes have methods with the same name.

Type Tracking

When dissolve processes a file, it:

Tracks variable assignments to determine types
Follows imports to resolve fully qualified names
Scans imported modules for @replace_me decorated functions
Uses this information to match function calls to their definitions

For example:

from mylib import OldClass
from other_lib import DifferentClass

obj1 = OldClass()
obj1.deprecated_method()  # Migrated - dissolve knows obj1 is OldClass

obj2 = DifferentClass()
obj2.deprecated_method()  # Not migrated - different class

Import Resolution

Dissolve resolves imports to handle various import styles:

# These imports of the same function:
from mylib.utils import old_function
from mylib.utils import old_function as legacy_func
import mylib.utils

# Are all recognized in these calls:
old_function()               # Direct import
legacy_func()                # Aliased import
mylib.utils.old_function()   # Module attribute access

Context Managers

Variable assignments in with statements are tracked:

with open_repo() as r:
    r.stage(files)  # dissolve tracks that r is the return type of open_repo()

Inheritance

Method resolution includes parent classes:

class Base:
    @replace_me()
    def old_method(self):
        return self.new_method()

class Child(Base):
    pass

obj = Child()
obj.old_method()  # Migrated even though method is defined in parent class

dissolve cleanup

The dissolve cleanup command is designed for library maintainers to remove
deprecated functions from their codebase after a deprecation period has ended.
This command removes the entire function definition, not just the @replace_me
decorator.

Audience: This command is primarily for library authors who want to clean up
their APIs after users have had time to migrate away from deprecated functions.

Important: This command removes the entire function definition, which will
break any code that still calls these functions. Only use this after:

Sufficient time has passed for users to migrate (based on your deprecation policy)
You've verified that usage of these functions has dropped to acceptable levels
You're prepared to release a new major version (if following semantic versioning)

Usage:

$ dissolve cleanup [options] path/to/code

Options:

--all: Remove all functions with @replace_me decorators regardless of version
--before VERSION: Remove only functions with decorators older than the specified version
--current-version VERSION: Remove functions marked with remove_in <= current version
-w, --write: Write changes back to files (default: print to stdout)
--check: Check if files have deprecated functions that can be removed without modifying them (exits with code 1 if changes are needed)

Examples:

Check if deprecated functions can be removed:

$ dissolve cleanup --check --current-version 2.0.0 mylib/
mylib/utils.py: needs function cleanup
mylib/core.py: up to date
$ echo $?
1

Remove functions scheduled for removal in version 2.0.0:

$ dissolve cleanup --current-version 2.0.0 --write mylib/
Modified: mylib/utils.py
Unchanged: mylib/core.py

Remove functions deprecated before version 2.0.0:

$ dissolve cleanup --before 2.0.0 --write mylib/

This will remove functions like those decorated with @replace_me(since="1.0.0")
but keep functions with @replace_me(since="2.0.0") and newer.

Typical workflow for library maintainers:

Add @replace_me(since="X.Y.Z", remove_in="A.B.C") to deprecated functions
Release version X.Y.Z with deprecation warnings
Wait for the planned removal version A.B.C
Run dissolve cleanup --current-version A.B.C --write to remove deprecated functions
Release version A.B.C as a new major version

dissolve check

The dissolve check command verifies that all @replace_me decorated
functions in your codebase can be successfully processed by the dissolve migrate command. This is useful for ensuring your deprecation decorators are
properly formatted.

Usage:

$ dissolve check path/to/code

This will:

Search for Python files with @replace_me decorated functions
Verify that each decorated function has a valid replacement expression
Report any functions that cannot be processed by migrate

Examples:

Check all files in a directory:

$ dissolve check myproject/
myproject/utils.py: 3 @replace_me function(s) can be replaced
myproject/core.py: 1 @replace_me function(s) can be replaced

When errors are found:

$ dissolve check myproject/broken.py
myproject/broken.py: ERRORS found
  Function 'old_func' cannot be processed by migrate

The command exits with code 1 if any errors are found, making it useful in CI
pipelines to ensure all deprecations are properly formatted.

Supported objects

The replace_me decorator can currently be applied to:

Functions
Async functions
Instance methods
Class methods (@classmethod)
Static methods (@staticmethod)
Properties (@property)
Classes
Module and class attributes (using replace_me(value))

Class Deprecation

Classes can be deprecated by applying the @replace_me decorator to the class definition. The deprecated class should act as a wrapper around the new class, with the __init__ method creating an instance of the replacement class:

from dissolve import replace_me

class UserManager:
    def __init__(self, database_url, cache_size=100):
        self.db = Database(database_url)
        self.cache = Cache(cache_size)
    
    def get_user(self, user_id):
        return self.db.fetch_user(user_id)

@replace_me(since="2.0.0")
class UserService:
    def __init__(self, database_url, cache_size=50):
        self._manager = UserManager(database_url, cache_size * 2)
    
    def get_user(self, user_id):
        return self._manager.get_user(user_id)
    
    def old_method_name(self, arg):
        return self._manager.new_method_name(arg)

When the deprecated class is instantiated, this will emit a deprecation warning:

>>> service = UserService("postgres://localhost", cache_size=25)
<stdin>:1: DeprecationWarning: <class UserService at 0x...> has been deprecated since 2.0.0; use 'UserManager("postgres://localhost", cache_size=25 * 2)' instead

The migration tool will replace all instantiations of the deprecated class with the wrapped class:

$ dissolve migrate --write myproject.py
# UserService("config", cache_size=100) becomes:
# UserManager("config", cache_size=100 * 2)

Class deprecation works with all instantiation patterns including direct calls, list comprehensions, and factory patterns:

# All of these will be migrated automatically:
service = UserService(db_url)
services = [UserService(url) for url in urls]
factory = lambda: UserService("default")

This approach allows library authors to provide full backward compatibility while guiding users to the new API. The deprecated class acts as a transparent wrapper that forwards method calls to the new implementation, and the migration tool automatically updates all usage sites to use the wrapped class directly.

Dissolve will automatically determine the appropriate replacement expression
based on the body of the decorated object. In some cases, this is not possible,
such as when the body is a complex expression or when the object is a lambda
function.

Attribute Deprecation

Module-level constants and class attributes can be deprecated using replace_me as a function that wraps the value:

from dissolve import replace_me

# Module-level attribute
OLD_API_URL = replace_me("https://api.example.com/v2")

# Class attribute
class Config:
    OLD_TIMEOUT = replace_me(30)
    OLD_DEBUG_MODE = replace_me(True)

When these attributes are used in code, the migration tool will replace them with the literal values:

$ dissolve migrate --write myproject.py
# Before:
# url = OLD_API_URL
# timeout = Config.OLD_TIMEOUT

# After:
# url = "https://api.example.com/v2"
# timeout = 30

This is particularly useful for deprecating configuration constants that have been replaced by new values or moved to different locations. The replace_me() function call serves as a marker for the migration tool without adding any runtime overhead.

Async Function Deprecation

Async functions are fully supported and work just like regular functions:

from dissolve import replace_me
import asyncio

async def new_fetch_data(url, timeout=30):
    # Modern implementation
    return await fetch_with_timeout(url, timeout)

@replace_me(since="3.0.0")
async def old_fetch_data(url):
    return await new_fetch_data(url, timeout=30)

When called, this will emit:

>>> await old_fetch_data("https://api.example.com")
<stdin>:1: DeprecationWarning: <function old_fetch_data at 0x...> has been deprecated since 3.0.0; use 'await new_fetch_data('https://api.example.com', timeout=30)' instead

The replacement expression correctly preserves the await keyword for async calls.

Class Methods and Static Methods

Class methods and static methods are fully supported. The @replace_me decorator
can be combined with @classmethod and @staticmethod decorators:

from dissolve import replace_me

class DataProcessor:
    @classmethod
    @replace_me(since="2.0.0")
    def old_process_data(cls, data):
        return cls.new_process_data(data.strip().upper())
    
    @classmethod
    def new_process_data(cls, processed_data):
        return f"Processed: {processed_data}"

    @staticmethod
    @replace_me(since="2.0.0")
    def old_utility_func(value):
        return new_utility_func(value * 10)

When called, these will emit appropriate deprecation warnings:

>>> DataProcessor.old_process_data("  hello  ")
<stdin>:1: DeprecationWarning: <function DataProcessor.old_process_data at 0x...> has been deprecated since 2.0.0; use 'DataProcessor.new_process_data('  hello  '.strip().upper())' instead

>>> DataProcessor.old_utility_func(5)
<stdin>:1: DeprecationWarning: <function DataProcessor.old_utility_func at 0x...> has been deprecated since 2.0.0; use 'new_utility_func(5 * 10)' instead

The migration tool will correctly replace these calls:

$ dissolve migrate --write myproject.py
# DataProcessor.old_process_data("test") becomes:
# DataProcessor.new_process_data("test".strip().upper())

Optional Dependency Usage

If you don't want to add a runtime dependency on dissolve, you can define a
fallback implementation that mimics dissolve's basic deprecation warning
functionality:

try:
    from dissolve import replace_me
except ModuleNotFoundError:
    import warnings

    def replace_me(since=None, remove_in=None):
        def decorator(func):
            def wrapper(*args, **kwargs):
                msg = f"{func.__name__} has been deprecated"
                if since:
                    msg += f" since {since}"
                if remove_in:
                    msg += f" and will be removed in {remove_in}"
                msg += ". Consider running 'dissolve migrate' to automatically update your code."
                warnings.warn(msg, DeprecationWarning, stacklevel=2)
                return func(*args, **kwargs)
            return wrapper
        return decorator

This fallback implementation provides the same decorator interface as
dissolve's replace_me decorator. When dissolve is installed, you get full
deprecation warnings with replacement suggestions and migration support. When
it's not installed, you still get basic deprecation warnings that include a
suggestion to use dissolve's migration tool.

Package profile

dissolve

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description