API documentation

The following documentation is based on the source code of version 2.0 of the npm-accel package.

Available modules

npm_accel

Accelerator for npm, the Node.js package manager.

npm_accel.KNOWN_INSTALLERS = ('npm', 'yarn', 'pnpm', 'npm-cache')

A tuple of strings with the names of supported Node.js installers.

class npm_accel.NpmAccel(**kw)

Python API for npm-accel.

When you create an NpmAccel object you’re required to provide a context by passing a keyword argument to the constructor. The following writable properties can be set in this same way: cache_directory, cache_limit, context, installer_name, production, read_from_cache, write_to_cache. Once you’ve initialized npm-accel the most useful method to call is install().

cache_directory

The absolute pathname of the directory where node_modules directories are cached (a string).

Note

The cache_directory property is a custom_property. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

cache_limit

The maximum number of tar archives to preserve in the cache (an integer, defaults to 20).

The environment variable $NPM_ACCEL_CACHE_LIMIT can be used to override the default value of this option.

Note

The cache_limit property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

context

A command execution context created using executor.contexts.

Note

The context property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named context (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

default_installer

The name of the default installer to use (either ‘npm’ or ‘yarn’).

When the yarn program is available in the $PATH the value of default_installer will be ‘yarn’, otherwise it falls back to ‘npm’.

Note

The default_installer property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

installer_method

The method corresponding to installer_name (a callable).

Raises:ValueError if the value of installer_name is not supported.

installer_name

The name of the installer to use (one of the strings in KNOWN_INSTALLERS).

The default value of installer_name is default_installer. When you try to set installer_name to a name that is not included in KNOWN_INSTALLERS a ValueError exception will be raised. When you try to set installer_name to the name of an installer that is not available a warning message will be logged and default_installer is used instead.

Note

The installer_name property is a custom_property. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

installer_version

The installer version according to the ${installer_name} --version command (a string).

Note

The installer_version property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

nodejs_interpreter

The name of the Node.js interpreter (a string).

The official name of the Node.js interpreter is simply node, however on Debian based systems this name conflicts with another program provided by a system package (ax25-node) which predates the existence of the Node.js interpreter. For this reason Debian calls the Node.js interpreter nodejs instead.

This property first checks whether the nodejs program is available (because it is the less ambiguous name of the two) and if that fails it will check if the node program is available.

Raises:MissingNodeInterpreterError when neither of the expected programs is available.

Note

The nodejs_interpreter property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

nodejs_version

The output of the nodejs --version or `node --version command (a string).

Raises:MissingNodeInterpreterError when neither of the expected programs is available.

Note

The nodejs_version property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

production

True if devDependencies should be ignored, False to have them installed.

The value of production defaults to True when the environment variable $NODE_ENV is set to production, otherwise it defaults to False.

Note

The production property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

production_option

One of the strings --production=true or --production=false (depending on production).

This command line option is given to the npm install, yarn, pnpm and npm-cache commands to explicitly switch between production and development installations.

read_from_cache

True if npm-accel is allowed to read from its cache, False otherwise.

Note

The read_from_cache property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

write_to_cache

True if npm-accel is allowed to write to its cache, False otherwise.

Note

The write_to_cache property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

add_to_cache(modules_directory, file_in_cache)

Add a node_modules directory to the cache.

Parameters:

• modules_directory – The pathname of the node_modules directory (a string).
• file_in_cache – The pathname of the archive in the cache (a string).

Raises:

Any exceptions raised by the executor.contexts module.

This method generates the tar archive under a temporary name inside the cache directory and then renames it into place atomically, in order to avoid race conditions where multiple concurrent npm-accel commands try to use partially generated cache entries.

The temporary names are generated by appending a randomly generated integer number to the original filename (with a dash to delimit the original filename from the number).

benchmark(directory, iterations=2, reset_caches=True, silent=False)

Benchmark npm install, yarn, pnpm, npm-accel and npm-cache.

Parameters:

• directory – The pathname of a directory with a package.json file (a string).
• iterations – The number of times to run each installation command.
• reset_caches – True to reset all caches before the first iteration of each installation method, False otherwise.
• silent – Used to set silent.

Raises:

Any exceptions raised by the executor.contexts module.

clean_cache()

Remove old and unused archives from the cache directory.

clear_directory(directory)

Make sure a directory exists and is empty.

Parameters:directory – The pathname of the directory (a string). Raises:Any exceptions raised by the executor.contexts module.

Note

If the directory already exists it will be removed and recreated in order to remove any existing contents. This may change the ownership and permissions of the directory. If this ever becomes a problem for someone I can improve it to preserve the metadata.

extract_dependencies(package_file)

Extract the relevant dependencies from a package.json file.

Parameters:package_file – The pathname of the file (a string). Returns:A dictionary with the relevant dependencies. Raises:MissingPackageFileError when the given directory doesn’t contain a package.json file.

If no dependencies are extracted from the package.json file a warning message is logged but it’s not considered an error.

find_archives()

Find the absolute pathnames of the archives in the cache directory.

Returns:A generator of filenames (strings).

get_cache_file(dependencies)

Compute the filename in the cache for the given dependencies.

Parameters:dependencies – A dictionary of dependencies like those returned by extract_dependencies(). Returns:The absolute pathname of the file in the cache (a string).

get_cache_key(dependencies)

Compute the cache key (fingerprint) for the given dependencies.

Parameters:dependencies – A dictionary of dependencies like those returned by extract_dependencies(). Returns:A 40-character hexadecimal SHA1 digest (a string).

In addition to the dependencies the values of nodejs_version and installer_version are used to compute the cache key, this is to make sure that upgrades to Node.js and the installer don’t cause problems.

get_metadata_file(file_in_cache)

Get the name of the metadata file for a given file in the cache.

Parameters:file_in_cache – The pathname of the archive in the cache (a string). Returns:The absolute pathname of the metadata file (a string).

install(directory, silent=False)

Install Node.js package(s) listed in a package.json file.

Parameters:

• directory – The pathname of a directory with a package.json file (a string).
• silent – Used to set silent.

Returns:

The result of extract_dependencies().

install_from_cache(file_in_cache, modules_directory)

Populate a node_modules directory by unpacking an archive from the cache.

Parameters:

• file_in_cache – The pathname of the archive in the cache (a string).
• modules_directory – The pathname of the node_modules directory (a string).

Raises:

Any exceptions raised by the executor.contexts module.

If the directory already exists it will be removed and recreated in order to remove any existing contents before the archive is unpacked.

install_with_npm(directory, silent=False)

Use npm install to install dependencies.

Parameters:

• directory – The pathname of a directory with a package.json file (a string).
• silent – Used to set silent.

Raises:

Any exceptions raised by the executor.contexts module.

install_with_npm_cache(directory, silent=False)

Use npm-cache to install dependencies.

Parameters:

• directory – The pathname of a directory with a package.json file (a string).
• silent – Used to set silent.

Raises:

Any exceptions raised by the executor.contexts module.

Warning

When I tried out npm-cache for the second time I found out that it unconditionally includes both production dependencies and devDependencies in the cache keys that it calculates, thereby opening the door for ‘cache poisoning’. For more details please refer to npm-cache issue 74. Currently npm-accel does not work around this problem, so consider yourself warned ;-).

install_with_pnpm(directory, silent=False)

Use pnpm to install dependencies.

Parameters:

• directory – The pathname of a directory with a package.json file (a string).
• silent – Used to set silent.

Raises:

Any exceptions raised by the executor.contexts module.

install_with_yarn(directory, silent=False)

Use yarn to install dependencies.

Parameters:

• directory – The pathname of a directory with a package.json file (a string).
• silent – Used to set silent.

Raises:

Any exceptions raised by the executor.contexts module.

preserve_contents(**kwds)

Restore the contents of a file after the context ends.

Parameters:filename – The pathname of the file (a string). Returns:A context manager.

read_metadata(file_in_cache)

Read the metadata associated with an archive in the cache.

Parameters:file_in_cache – The pathname of the archive in the cache (a string). Returns:A dictionary with cache metadata. If the cache metadata file cannot be read or its contents can’t be parsed as JSON then an empty dictionary is returned.

write_metadata(file_in_cache, **overrides)

Create or update the metadata file associated with an archive in the cache.

Parameters:

• file_in_cache – The pathname of the archive in the cache (a string).
• overrides – Any key/value pairs to add to the metadata.

npm_accel.auto_decode(text)

Decode a byte string by guessing the text encoding.

Parameters:text – A byte string. Returns:A Unicode string.

npm_accel.cli

Usage: npm-accel [OPTIONS] [DIRECTORY]

The npm-accel program is a wrapper for npm (the Node.js package manager) that optimizes one specific use case: Building a “node_modules” directory from a “package.json” file as quickly as possible.

It works on the assumption that you build “node_modules” directories more frequently then you change the contents of “package.json” files, because it computes a fingerprint of the dependencies and uses that fingerprint as a cache key, to cache the complete “node_modules” directory in a tar archive.

Supported options:

Option	Description
-p, --production	Don’t install modules listed in “devDependencies”.
-i, --installer=NAME	Set the installer to use. Supported values for NAME are “npm”, “yarn”, “pnpm” and “npm-cache”. When yarn is available it will be selected as the default installer, otherwise the default is npm.
-u, --update	Don’t read from the cache but do write to the cache. If you suspect a cache entry to be corrupt you can use --update to ‘refresh’ the cache entry.
-n, --no-cache	Disallow writing to the cache managed by npm-accel (reading is still allowed though). This option does not disable internal caching performed by npm, yarn, pnpm and npm-cache.
-c, --cache-directory=DIR	Set the pathname of the directory where the npm-accel cache is stored.
-l, --cache-limit=COUNT	Set the maximum number of tar archives to preserve. When the cache directory contains more than COUNT archives the least recently used archives are removed. Defaults to 20. The environment variable $NPM_ACCEL_CACHE_LIMIT provides a convenient way to customize this option in CI and build environments.
-b, --benchmark	Benchmark and compare the following installation methods: npm install yarn pnpm npm-accel npm-cache The first method performs no caching (except for the HTTP caching that’s native to npm) while the other four methods each manage their own cache (that is to say, the caching logic of npm-accel is only used in step 4). Warning: Benchmarking wipes the caches managed by npm, yarn, pnpm, npm-accel and npm-cache in order to provide a fair comparison (you can override this in the Python API but not on the command line).
-r, --remote-host=SSH_ALIAS	Operate on a remote system instead of the local system. The SSH_ALIAS argument gives the SSH alias of the remote host.
-v, --verbose	Increase logging verbosity (can be repeated).
-q, --quiet	Decrease logging verbosity (can be repeated).
--version	Report the version of npm-accel.
-h, --help	Show this message and exit.

npm_accel.cli.main()

Command line interface for the npm-accel program.

npm_accel.exceptions

Custom exceptions that are raised explicitly by npm-accel.

exception npm_accel.exceptions.NpmAccelError

Base class for exceptions that are raised explicitly by npm-accel.

exception npm_accel.exceptions.MissingPackageFileError

Raised when the given directory doesn’t contain a package.json file.

exception npm_accel.exceptions.MissingNodeInterpreterError

Raised when the Node.js interpreter is not available on the $PATH.