INSTLD: the simplest package management

Thanks to this package, it is very easy to manage the lifecycle of packages.

• ⚡ Run your code without installing libraries.
• ⚡ You can use 2 different versions of the same library in the same program.
• ⚡ You can use incompatible libraries in the same project, as well as libraries with incompatible/conflicting dependencies.
• ⚡ It's easy to share written scripts. The script file becomes self-sufficient - the user does not need to install the necessary libraries.
• ⚡ The library does not leave behind "garbage". After the end of the program, no additional files remain in the system.

Table of contents

• Quick start
• REPL mode
• Script launch mode
• Context manager mode
  • Installing multiple packages
  • Options
  • Using an existing virtual environment
  • Output and logging
• Special comment language
• Using multiple environments
• How does it work?

Quick start

Install it:

pip install instld

And use the library in one of three ways: by typing commands via REPL, by running your script through it or by importing a context manager from there.

If you run the script like this, all dependencies will be automatically installed when the application starts and deleted when it stops:

instld script.py

The REPL mode works in a similar way, you just need to type instld in the console to enter it.

You can also call the context manager from your code:

import instld

with instld('some_package'):
    import some_module

Read more about each method, its capabilities and limitations below.

REPL mode

REPL mode is the fastest and easiest way to try out other people's libraries for your code. Just type this in your console:

instld

After that you will see a welcome message similar to this:

⚡ INSTLD REPL based on
Python 3.11.6 (main, Oct  2 2023, 13:45:54) [Clang 15.0.0 (clang-1500.0.40.1)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

>>>

Enjoy the regular Python interactive console mode! Any libraries that you ask for will be installed within the session, and after exiting it, they will be deleted without a trace. You don't need to "clean up" anything after exiting the console.

In this mode, a special comment language is fully supported.

Script launch mode

You can use instld to run your script from a file. To do this, you need to run a command like this in the console:

instld script.py

The contents of the script will be executed in the same way as if you were running it through the python script.py command. If necessary, you can pass additional arguments to the command line, as if you are running a regular Python script. However, if your program has imports of any packages other than the built-in ones, they will be installed automatically. Installed packages are automatically cleaned up when you exit the program, so they don't leave any garbage behind.

In this mode, as in REPL, a special comment language is fully supported.

Context manager mode

You can also use instld to install and use packages in runtime. The context manager instld generates a context. While you are inside the context manager, you can import modules using the usual import command:

with instld('some_package'):
    import some_module

However, there are cases when you need the module to be imported strictly from a given context. In this case, it is better to use the import_here method:

with instld('some_package') as context:
    module = context.import_here('some_module')

The library provides isolation of various contexts among themselves, so in the second case, the module will be imported strictly from the context that you need.

⚠️ Some modules use lazy imports. If such an import happens after exiting the context manager, it will break your program. Please make sure that all the internal components of the libraries used have been initialized before the execution of your code goes out of context.

Installing multiple packages

You can install several packages by specifying their names separated by commas:

with instld('package_1', 'package_2', 'package_3') as context:
    module_1 = context.import_here('module_1')
    module_2 = context.import_here('module_2')
    module_3 = context.import_here('module_3')

In this case, all packages will be installed in one context and you can import them all from there.

You can also create separate contexts for different packages:

with instld('package_1') as context_1:
    with instld('package_2') as context_2:
        with instld('package_3') as context_3:
            module_1 = context_1.import_here('module_1')
            module_2 = context_2.import_here('module_2')
            module_3 = context_3.import_here('module_3')

In this case, each package was installed in its own independent context, and we import each module from the context where the corresponding package was installed.

This capability is very powerful. You can place libraries in different contexts that are incompatible with each other. You can also install different versions of the same library in neighboring contexts. Here's how it will work using the Flask example:

with instld('flask==2.0.2') as context_1:
    with instld('flask==2.0.0') as context_2:
        flask_1 = context_1.import_here('flask')
        flask_2 = context_2.import_here('flask')

        print(flask_1.__version__)  # 2.0.2
        print(flask_2.__version__)  # 2.0.0

⚠️ Keep in mind that although inter-thread isolation is used inside the library, working with contexts is not completely thread-safe. You can write code in such a way that two different contexts import different modules in separate threads at the same time. In this case, you may get paradoxical results. Therefore, it is recommended to additionally isolate with mutexes all cases where you import something from contexts in different threads.

Options

You can use any options available for pip. To do this, you need to slightly change the name of the option, replacing the hyphens with underscores, and pass it as an argument to instld. Here is an example of how using the --index-url option will look like:

with instld('super_test_project==0.0.1', index_url='https://test.pypi.org/simple/'):
    import super_test

You cannot use options that tell pip where to install libraries.

Using an existing virtual environment

By default, through the context manager, packages are installed in a temporary virtual environment, which is deleted after exiting the context. However, if you want to install the package in a permanent environment, there is also a way to do this: use the where argument.

with instld('package', where='path/to/the/venv'):
    import package

When manually specifying the path to the virtual environment directory, you need to consider several points:

1. The format of the separator differs in different operating systems. For example, in Linux it is /, and in Windows it is \. To make your code multiplatform, use os.path.join to define the path.
2. You need to make sure that the virtual environment that you are passing the path to is created by the same Python interpreter that you use to run your code. Virtual environments created by different interpreters are not compatible with each other. For the same reasons, it is not worth storing virtual environment files in Git.

Output and logging

By default, you can see the output of the installation progress in the console:

>>> with instld('flask'):
...     import flask
...
Collecting flask
  Using cached Flask-2.3.2-py3-none-any.whl (96 kB)
Collecting click>=8.1.3
  Using cached click-8.1.3-py3-none-any.whl (96 kB)
Collecting importlib-metadata>=3.6.0
  Using cached importlib_metadata-6.6.0-py3-none-any.whl (22 kB)
Collecting Jinja2>=3.1.2
  Using cached Jinja2-3.1.2-py3-none-any.whl (133 kB)
Collecting Werkzeug>=2.3.3
  Using cached Wer