| Name | mxdev JSON |
| Version |
4.0.2
JSON |
| download |
| home_page | |
| Summary | Enable to work with Python projects containing lots of packages, of which you only want to develop some. |
| upload_time | 2024-03-12 23:45:55 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | BSD 2-Clause License |
| keywords |
pip
vcs
git
development
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Mixed development source packages on top of stable constraints using pip
*mxdev* [mɪks dɛv] is a utility that makes it easy to work with Python projects containing lots of packages, of which you only want to develop some.
It builds on top of the idea to have stable version constraints and then develop from a VCS on top of it.
As part of the above use-case sometimes versions of the stable constraints need an override with a different (i.e. newer) version.
Other software follow the same idea are [mr.developer](https://pypi.org/project/mr.developer) for Python's *zc.buildout* or [mrs-developer](https://www.npmjs.com/package/mrs-developer) for NPM packages.
**[Star us on Github](https://github.com/mxstack/mxdev)**
### Overview
mxdev procedure is:
1. Configuration is read,
2. Requirements and constraints (given in the configuration) are read.
3. Sources from VCS are fetched into a target directory,
4. Modified constraints (handled packages commented, overridden versions replaced) and requirements (handled packages as editable from sources) are written.
mxdev will **not** run *pip* for you!
### Configuration
Given a `requirements.txt` (or similar named) file which itself references a `constraints.txt` file inside.
Create an INI file, like `mx.ini` in [configparser.ExtendedInterpolation](https://docs.python.org/3/library/configparser.html#configparser.ExtendedInterpolation) syntax.
### Main section `[settings]`
The **main section** must be called `[settings]`, even if kept empty.
In the main sections the input and output files are defined.
#### `requirements-in`
Main requirements file to start with. This can be an URL too.
If given an empty value mxdev will only generate output from the information given in INI file itself.
Default: `requirements.txt`
#### `requirements-out`
Output of the combined requirements including development sources to be used later with `pip install`.
Default: `requirements-mxdev.txt`
#### `constraints-out`
Output of the combined constraints.
Default: `constraints-mxdev.txt`
#### `include`
Include one or more other INI files.
The included file is read before the main file, so the main file overrides included settings.
Included files may include other files.
Innermost inclusions are read first.
If an included file is an HTTP-URL, it is loaded from there.
If the included file is a relative path, it is loaded relative to the parents directory or URL.
The feature utilizes the [ConfigParser feature to read multiple files at once](https://docs.python.org/3/library/configparser.html#configparser.ConfigParser.read).
Default: empty
#### `default-target`
Target directory for sources from VCS. Default: `./sources`
#### `default-install-mode`
Default for `install-mode` on section, read there for details
Allowed values: `direct` or `skip`
Default: `direct`
#### `default-update`
Default for `update` on section, read there for details
Allowed values: `yes` or `no`
Default: `yes`
#### `threads`
Number of threads to fetch sources in parallel with.
Speeds up fetching from VCS.
Default: `4`
#### `offline`
Do not fetch any sources.
Handy if working offline.
Default: `False`
#### `version-overrides`
Override package versions which are already defined in a dependent constraints file.
I.e. an upstream *constraints.txt* contains already `somefancypackage==2.0.3`.
Given that, for some reason (like with my further developed sources), we need version 3.0.0 of the above package.
Then in this section, this can be defined as:
```INI
[settings]
version-overrides =
somefancypackage==3.0.0
otherpackage==33.12.1
```
It is possible to add as many overrides as needed.
When writing the *constraints-out*, the new version will be taken into account.
If there is a source section defined for the same package, the source will be used and entries here are ignored.
#### `ignores`
Ignore packages that are already defined in a dependent constraints file.
No new version will be provided.
This is specifically handy if a package is going to be installed editable from local file system (like `-e .`), but was already pinned in an upstream constraints file.
This can be defined as:
```INI
[settings]
ignores =
somefancypackage
otherpackage
```
#### `default-use`
True by default. When false, the source is not checked out,
and the version for this package is not overridden.
Additionally, custom variables can be defined as `key = value` pair.
Those can be referenced in other values as `${settings:key}` and will be expanded there.
#### `main-package`
mxdev can handle one Python package as main package directly via ini config.
If defined, it will be added as last entry in the resulting requirements out file.
This can be defined as:
```INI
[settings]
main-package = -e .[test]
```
If the main package is defined in a dependent constraint file, it's name must be added to `ignores`.
### Default settings
mxdev provides default settings which can be used inside package or custom
sections.
#### `directory`
Contains the current working directory and can be used like this
```INI
[sectionname]
param = ${settings:directory}/some/path
```
### Subsequent package source sections
All other sections are defining the sources to be used.
#### `[PACKAGENAME]`
The section name is the package name.
#### `url = URL`
The checkout URL of the repository.
The URL is required.
#### `pushurl = URL`
Optional a writable URL for pushes can be specified.
If the `pushurl` is set after initial checkout it is not applied.
To apply it remove the repository and checkout again.
#### `vcs = VCS`
The version control system to use.
Supported are:
- `git` (stable, tested)
- `fs` (stable, tested) - in fact no vcs, but points to a local directory.
This can be achieved without mxdev by using `-e PATH` in the requirements input file.
- `svn` (unstable, test needs rewrite)
- `gitsvn` (unstable, test needs rewrite)
- `hg` (unstable, test needs rewrite)
- `bzr` (unstable, test needs rewrite)
- `darcs` (unstable, test needs rewrite)
Defaults to `git`.
#### `branch = BRANCHNAME_OR_TAG`
The branch name or tag to checkout.
Defaults to `main`.
#### `extras = EXTRA1,EXTRA2`
Package extras to install. Default empty.
#### `subdirectory = SUBPATH`
For specifying the path to the Python package, when it is not in the root of the VCS directory.
Default empty.
#### `target`
The target directory for source from this section.
Default to default target directory configured in the main section `[settings]` `default-target =` value.
#### `install-mode`
There are different modes of pip installation
##### `skip`
Do not install with pip, just clone/update the repository
##### `direct`
Install the package using `pip -e PACKAGEPATH`.
Dependencies are resolved immediately
Defaults to default mode configured in main section `[settings]` `default-install-mode =` value.
#### `use`
True by default, unless `default-use` in the general settings is false.
When false, the source is not checked out,
and the version for this package is not overridden.
#### `submodules`
There are 3 different options:
##### `always`
(default) git submodules will always be checked out, they will be updated if already presen
##### `checkout`
submodules get only fetched during checkout, existing submodules stay untouche
##### `recursive`
Fetches submodules recursively, results in `git clone --recurse-submodules on` checkout and `submodule update --init --recursive` on update.
### Usage
Run `mxdev` (for more options run `mxdev --help`).
Mxdev will
1. **read** the configuration from `mx.ini`,
2. **fetch** the packages defined in the config file and
3. **write** a requirements and constraints file.
Now, use the generated requirements and constraints files with i.e. `pip install -r requirements-mxdev.txt`.
**mxdev >=4.0 needs pip version 23 at minimum to work properly**
## Example Configuration
### Example `mx.ini`
This looks like so:
```INI
[settings]
requirements-in = requirements.txt
requirements-out = requirements-mxdev.txt
contraints-out = constraints-mxdev.txt
version-overrides =
baz.baaz = 1.9.32
ignores =
my.ignoredpackage
# custom variables
github = git+ssh://git@github.com/
mygit = git+ssh://git@git.kup.tirol/
[foo.bar]
url = ${settings:github}orga/foo.bar.git
branch = fix99
extras = test,baz
[kup.fancyproject]
url = ${settings:mygit}customers/fancycorp/kup.fancyproject.git
branch = fix99
extras = test,baz
```
### Examples at GitHub
- ["new" plone.org backend](https://github.com/plone/plone.org/tree/main/backend)
- [Conestack](https://github.com/conestack/conestack/)
- (add more)
## Extending
The functionality of mxdev can be extended by hooks.
This is useful to generate additional scripts or files or automate any other setup steps related to mxdev's domain.
Extension configuration settings end up in the `mx.ini` file.
They can be added globally to the `settings` section, as dedicated config sections or package specific.
To avoid naming conflicts, all hook-related settings and config sections must be prefixed with a namespace.
It is recommended to use the package name containing the hook as a namespace.
This looks like so:
```INI
[settings]
myextension-global_setting = 1
[myextension-section]
setting = value
[foo.bar]
myextension-package_setting = 1
```
The extension is implemented as a subclass of `mxdev.Hook`:
```Python
from mxdev import Hook
from mxdev import State
class MyExtension(Hook):
namespace = None
"""The namespace for this hook."""
def read(self, state: State) -> None:
"""Gets executed after mxdev read operation."""
def write(self, state: State) -> None:
"""Gets executed after mxdev write operation."""
```
The default settings section from the INI file is available at `state.configuration.settings`.
The package configuration is available at `state.configuration.packages`.
Hook-related config sections are available at `state.configuration.hooks`.
The hook must be registered as an entry point in the `pyproject.toml` of your package:
```TOML
[project.entry-points.mxdev]
hook = "myextension:MyExtension"
```
## Rationale
### Problem
There is a constraint file like `-c constraints.txt` with a package `foo.bar` with a version pin.
Then it is not possible to install this package in a requirements file editable like `-r requirements.txt` with `-e git+ssh://git@github.com/orga/foo.bar.git@fix-99`.
Neither it is possible to override inherited version constraints with custom ones.
### Idea
A pre-processor fetches (as this can be an URL) and expands all `-c SOMEOTHER_FILE_OR_URL` and `-r SOMEOTHER_FILE_OR_URL` files into one, filtering out all packages given in a configuration file.
For each of those packages, a `-e ...` entry is generated instead and written to a new `TARGET.txt`.
Same is true for version overrides: a new entry is written to the resulting constraints file while the original version is disabled.
The configuration is read from a file `mx.ini` in *ExtendedInterpolation* INI syntax (YAML would be nice, but the package must have as less dependencies as possible to other packages).
### Trivia
Mx (generally pronounced like mix [mɪks], or [məks] in the UK) is meant to be a gender-neutral alternative to the titles Mr. and Ms. but also associates with the word "mix".
## Misc
The VCS-related code is taken from `mr.developer`.
Thanks to Florian Schulze and Contributors.
## Contributing
If you want to help with the development (improvement, update, bug-fixing, ...) of `mxdev` this is a great idea!
The code is located in the [GitHub MXStack Organization / mxdev](https://github.com/mxstack/mxdev).
You can fork it, work on the project and create a pull request.
Maintainers are Jens Klein and the [BlueDynamics Alliance](https://bluedynamics.com) developer team.
We appreciate any contribution! If you have an idea, found a bug, want to drop us a question, or a release is needed, please just file an issue at the [mxdev issue tracker](https://github.com/bluedynamics/mxdev/issues).
## Changes
## 4.0.2 (2024-03-13)
- Fix #42: deprecated use of `pkg_resoures` to load entry points and parse requirements.
This enables mxdev to work on Python 3.12, where `pkg_resources` is no longer installed by default in virtual_envs.
[jensens]
## 4.0.1 (2024-03-01)
- Fix specifying out a revision (#40)
[pbauer]
### 4.0.0 (2024-02-28)
- Breaking: Remove `--pre` on sources from generated `requirements-mxdev.txt`.
Usually it is not needed any longer, at least withy pip 23.x.
This is a breaking change if you rely on the `--pre` option being present in the generated file.
Now the `--pre` option should be added to `pip install` when the generated file is used.
This change enables the use of the generated file with the alternative pip replacement `uv`.
[jensens]
- Breaking: Drop official support for Python 3.7 (it is end of life).
[jensens]
- Document `mx.ini` sections `vcs` setting.
[jensens]
### 3.1.0 (2023-12-10)
- Feature: Provide `directory` default setting [rnix]
- Feature: Include other INI config files [jensens]
### 3.0.0 (2023-05-08)
- Removed leftover print [jensens]
### 3.0.0b3 (2023-04-23)
- Fix usage of `--install-option='pre'` and use `--pre` option in requirements files instead.
The install options are deprecated in pip 23 which Plone switched to recently.
More info:
https://github.com/pypa/pip/issues/11358
https://discuss.python.org/t/passing-command-line-arguments-to-pip-install-after-install-options-deprecation/22981/6
[thet, fredvd]
- Fix reading sections from the config parser without defaults if the section contains a setting that also exists as default.
[rnix]
- Do not write constraints out to the file if no constraints are defined.
[rnix]
- Add the `main-package` option to the settings.
[rnix]
### 3.0.0b2 (2023-02-07)
- In this package, use `pyproject.toml` and markdown for README et al.
[jensens]
- Add `use` option to sources, and `default-use` to the settings.
`default-use` is true by default.
When false, the source is not checked out, and the version for this package is not overridden.
[maurits]
### 3.0.0b1 (2022-11-21)
- Do not use `libvcs`, but recycled and updated (type hints, tests) `mr.developer` VCS code.
Code for GIT is tested well, code for SVN, Mercurial, Bazaar and DARCS needs contributors with knowledge in this area.
Additional options, like `pushurl`, ... (see README) were added.
`pip` style VCS URLs are not supported any longer.
[jensens, rnix, zworkb]
- Config parser options are now considered case-sensitive.
[rnix]
- Do not fail `mxdev` run if `requirements.txt` is missing.
[rnix]
- Add flag to only fetch repositories and skip generating files.
[rnix]
- Add flag to skip fetching of repositories.
[rnix]
- Add support for custom hooks.
[rnix]
- Rename `sources.ini` to `mx.ini` in the documentation.
[rnix]
- Introduce state object and pass it to read/fetch/write.
State object contains all required runtime data.
[rnix]
### 2.0.0 (2022-01-31)
- Depend on pip 22, where interdependency mode is no longer needed.
Remove all interdependency-related code.
[jensens]
- Better error message if the requirements-in file does not exist.
[jensens]
- Better last message with the full pip command.
[jensens]
- Allow empty `requirements-in` configuration.
[jensens]
### 1.1.0 (2021-12-29)
- Feature: Ignore existing constraints.
New setting `ignores` with a list of packages (one per line) to ignore constraints without providing a version.
[jensens]
### 1.0.1 (2021-12-21)
- Fix: If a developed package depends on another developed package the dependent package was ignored *sometimes* (!?).
Instead, the last release was taken.
Solution: Install it with the `--pre` option in order to allow the other non-final/in-development *release*.
[jensens]
### 1.0.0 (2021-12-12)
- Defaults for "outfiles" are `*-mxdev.txt` now.
[jensens]
### 1.0.0b4 (2021-12-07)
- Fix interdependency mode.
[jensens]
### 1.0.0b3 (2021-12-07)
- Fix: Do not apply override disabling on requirements.
[jensens]
### 1.0.0b2 (2021-12-07)
- Add feature: version overrides.
[jensens]
### 1.0.0b1 (2021-12-04)
- Add `-s` or `--silent` option.
[jensens]
- Beautified output.
[jensens]
- Fixed missing CR if `*.txt` does not end with a newline.
[jensens]
### 1.0.0a9 (2021-12-01)
- Added auto correction for pip URLs, so that GitHub or GitLab URLs can be used as copied in `sources.ini`.
[zworkb]
### 1.0.0a8 (2021-11-30)
- Added interdependency handling to avoid manual dependency order resolution.
[jensens, gogobd]
- Added skip mode to exclude packages from installation (clone/update only).
[jensens, gogobd]
- Removed position feature.
[jensens, gogobd]
### 1.0.0a7 (2021-11-30)
- Removed Workaround for libvcs and depend on libvcs>=0.10.1.
[jensens]
### 1.0.0a6 (2021-11-30)
- Workaround for libvcs bug https://github.com/vcs-python/libvcs/issues/295
[jensens, gogobd]
### 1.0.0a5 (2021-11-30)
- Workaround for libvcs bug https://github.com/vcs-python/libvcs/issues/293
[jensens, gogobd]
### 1.0.0a4 (2021-11-29)
- Fix: editable can be configured to be processed before or after initial requirements.
[jensens]
### 1.0.0a3 (2021-11-23)
- Fix #1: Re-run of pip vanishes committed changes
[jensens]
### 1.0.0a2 (2021-11-21)
- Fix/simplify packaging.
[jensens]
- Implement subdirectory editable install
[jensens]
- Implement package extras
[jensens]
### 1.0.0a1 (2021-11-21)
- Initial work.
[jensens]
## License
Copyright (c) 2022-2023, mxstack Contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Raw data
{
"_id": null,
"home_page": "",
"name": "mxdev",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "pip,vcs,git,development",
"author": "",
"author_email": "MX Stack Developers <dev@bluedynamics.com>",
"download_url": "https://files.pythonhosted.org/packages/38/3d/7ebf5031d14146f28fabda056bb54f7df74fb76e1df4558854f5598a383e/mxdev-4.0.2.tar.gz",
"platform": null,
"description": "# Mixed development source packages on top of stable constraints using pip\n\n*mxdev* [m\u026aks d\u025bv] is a utility that makes it easy to work with Python projects containing lots of packages, of which you only want to develop some.\n\nIt builds on top of the idea to have stable version constraints and then develop from a VCS on top of it.\n\nAs part of the above use-case sometimes versions of the stable constraints need an override with a different (i.e. newer) version.\nOther software follow the same idea are [mr.developer](https://pypi.org/project/mr.developer) for Python's *zc.buildout* or [mrs-developer](https://www.npmjs.com/package/mrs-developer) for NPM packages.\n\n**[Star us on Github](https://github.com/mxstack/mxdev)**\n\n\n### Overview\n\nmxdev procedure is:\n\n1. Configuration is read,\n2. Requirements and constraints (given in the configuration) are read.\n3. Sources from VCS are fetched into a target directory,\n4. Modified constraints (handled packages commented, overridden versions replaced) and requirements (handled packages as editable from sources) are written.\n\nmxdev will **not** run *pip* for you!\n\n\n### Configuration\n\nGiven a `requirements.txt` (or similar named) file which itself references a `constraints.txt` file inside.\n\nCreate an INI file, like `mx.ini` in [configparser.ExtendedInterpolation](https://docs.python.org/3/library/configparser.html#configparser.ExtendedInterpolation) syntax.\n\n\n### Main section `[settings]`\n\nThe **main section** must be called `[settings]`, even if kept empty.\nIn the main sections the input and output files are defined.\n\n#### `requirements-in`\n\nMain requirements file to start with. This can be an URL too.\n\nIf given an empty value mxdev will only generate output from the information given in INI file itself.\n\nDefault: `requirements.txt`\n\n#### `requirements-out`\n\nOutput of the combined requirements including development sources to be used later with `pip install`.\nDefault: `requirements-mxdev.txt`\n\n#### `constraints-out`\n\nOutput of the combined constraints.\n\nDefault: `constraints-mxdev.txt`\n\n#### `include`\n\nInclude one or more other INI files.\n\nThe included file is read before the main file, so the main file overrides included settings.\nIncluded files may include other files.\nInnermost inclusions are read first.\n\nIf an included file is an HTTP-URL, it is loaded from there.\n\nIf the included file is a relative path, it is loaded relative to the parents directory or URL.\n\nThe feature utilizes the [ConfigParser feature to read multiple files at once](https://docs.python.org/3/library/configparser.html#configparser.ConfigParser.read).\n\nDefault: empty\n\n#### `default-target`\n\nTarget directory for sources from VCS. Default: `./sources`\n\n#### `default-install-mode`\n\nDefault for `install-mode` on section, read there for details\nAllowed values: `direct` or `skip`\n\nDefault: `direct`\n\n#### `default-update`\nDefault for `update` on section, read there for details\n\nAllowed values: `yes` or `no`\n\nDefault: `yes`\n\n#### `threads`\n\nNumber of threads to fetch sources in parallel with.\nSpeeds up fetching from VCS.\n\nDefault: `4`\n\n#### `offline`\n\nDo not fetch any sources.\nHandy if working offline.\n\nDefault: `False`\n\n#### `version-overrides`\n\nOverride package versions which are already defined in a dependent constraints file.\nI.e. an upstream *constraints.txt* contains already `somefancypackage==2.0.3`.\nGiven that, for some reason (like with my further developed sources), we need version 3.0.0 of the above package.\n\nThen in this section, this can be defined as:\n\n```INI\n[settings]\nversion-overrides =\n somefancypackage==3.0.0\n otherpackage==33.12.1\n```\n\nIt is possible to add as many overrides as needed.\nWhen writing the *constraints-out*, the new version will be taken into account.\nIf there is a source section defined for the same package, the source will be used and entries here are ignored.\n\n#### `ignores`\n\nIgnore packages that are already defined in a dependent constraints file.\nNo new version will be provided.\nThis is specifically handy if a package is going to be installed editable from local file system (like `-e .`), but was already pinned in an upstream constraints file.\n\nThis can be defined as:\n\n```INI\n[settings]\nignores =\n somefancypackage\n otherpackage\n```\n\n#### `default-use`\n\nTrue by default. When false, the source is not checked out,\nand the version for this package is not overridden.\nAdditionally, custom variables can be defined as `key = value` pair.\nThose can be referenced in other values as `${settings:key}` and will be expanded there.\n\n#### `main-package`\n\nmxdev can handle one Python package as main package directly via ini config.\nIf defined, it will be added as last entry in the resulting requirements out file.\n\nThis can be defined as:\n\n```INI\n[settings]\nmain-package = -e .[test]\n```\n\nIf the main package is defined in a dependent constraint file, it's name must be added to `ignores`.\n\n### Default settings\n\nmxdev provides default settings which can be used inside package or custom\nsections.\n\n#### `directory`\n\nContains the current working directory and can be used like this\n\n```INI\n[sectionname]\nparam = ${settings:directory}/some/path\n```\n\n### Subsequent package source sections\n\nAll other sections are defining the sources to be used.\n\n#### `[PACKAGENAME]`\n\nThe section name is the package name.\n\n#### `url = URL`\n\nThe checkout URL of the repository.\n\nThe URL is required.\n\n#### `pushurl = URL`\n\nOptional a writable URL for pushes can be specified.\n\nIf the `pushurl` is set after initial checkout it is not applied.\nTo apply it remove the repository and checkout again.\n\n#### `vcs = VCS`\n\nThe version control system to use.\n\nSupported are:\n- `git` (stable, tested)\n- `fs` (stable, tested) - in fact no vcs, but points to a local directory.\n This can be achieved without mxdev by using `-e PATH` in the requirements input file.\n- `svn` (unstable, test needs rewrite)\n- `gitsvn` (unstable, test needs rewrite)\n- `hg` (unstable, test needs rewrite)\n- `bzr` (unstable, test needs rewrite)\n- `darcs` (unstable, test needs rewrite)\n\nDefaults to `git`.\n\n#### `branch = BRANCHNAME_OR_TAG`\n\nThe branch name or tag to checkout.\n\nDefaults to `main`.\n\n#### `extras = EXTRA1,EXTRA2`\n\nPackage extras to install. Default empty.\n\n#### `subdirectory = SUBPATH`\n\nFor specifying the path to the Python package, when it is not in the root of the VCS directory.\n\nDefault empty.\n\n#### `target`\n\nThe target directory for source from this section.\n\nDefault to default target directory configured in the main section `[settings]` `default-target =` value.\n\n#### `install-mode`\n\nThere are different modes of pip installation\n\n##### `skip`\n\nDo not install with pip, just clone/update the repository\n\n##### `direct`\n\nInstall the package using `pip -e PACKAGEPATH`.\nDependencies are resolved immediately\n\nDefaults to default mode configured in main section `[settings]` `default-install-mode =` value.\n\n#### `use`\n\nTrue by default, unless `default-use` in the general settings is false.\nWhen false, the source is not checked out,\nand the version for this package is not overridden.\n\n#### `submodules`\n\nThere are 3 different options:\n\n##### `always`\n\n(default) git submodules will always be checked out, they will be updated if already presen\n\n##### `checkout`\n\nsubmodules get only fetched during checkout, existing submodules stay untouche\n\n##### `recursive`\n\nFetches submodules recursively, results in `git clone --recurse-submodules on` checkout and `submodule update --init --recursive` on update.\n\n### Usage\n\nRun `mxdev` (for more options run `mxdev --help`).\n\nMxdev will\n\n1. **read** the configuration from `mx.ini`,\n2. **fetch** the packages defined in the config file and\n3. **write** a requirements and constraints file.\n\nNow, use the generated requirements and constraints files with i.e. `pip install -r requirements-mxdev.txt`.\n\n**mxdev >=4.0 needs pip version 23 at minimum to work properly**\n\n## Example Configuration\n\n### Example `mx.ini`\n\nThis looks like so:\n\n```INI\n[settings]\nrequirements-in = requirements.txt\nrequirements-out = requirements-mxdev.txt\ncontraints-out = constraints-mxdev.txt\n\nversion-overrides =\n baz.baaz = 1.9.32\n\nignores =\n my.ignoredpackage\n\n# custom variables\ngithub = git+ssh://git@github.com/\nmygit = git+ssh://git@git.kup.tirol/\n\n[foo.bar]\nurl = ${settings:github}orga/foo.bar.git\nbranch = fix99\nextras = test,baz\n\n[kup.fancyproject]\nurl = ${settings:mygit}customers/fancycorp/kup.fancyproject.git\nbranch = fix99\nextras = test,baz\n```\n\n### Examples at GitHub\n\n- [\"new\" plone.org backend](https://github.com/plone/plone.org/tree/main/backend)\n- [Conestack](https://github.com/conestack/conestack/)\n- (add more)\n\n\n## Extending\n\nThe functionality of mxdev can be extended by hooks.\nThis is useful to generate additional scripts or files or automate any other setup steps related to mxdev's domain.\n\nExtension configuration settings end up in the `mx.ini` file.\nThey can be added globally to the `settings` section, as dedicated config sections or package specific.\nTo avoid naming conflicts, all hook-related settings and config sections must be prefixed with a namespace.\n\nIt is recommended to use the package name containing the hook as a namespace.\n\nThis looks like so:\n\n```INI\n[settings]\nmyextension-global_setting = 1\n\n[myextension-section]\nsetting = value\n\n[foo.bar]\nmyextension-package_setting = 1\n```\nThe extension is implemented as a subclass of `mxdev.Hook`:\n\n```Python\n\nfrom mxdev import Hook\nfrom mxdev import State\n\nclass MyExtension(Hook):\n\n namespace = None\n \"\"\"The namespace for this hook.\"\"\"\n\n def read(self, state: State) -> None:\n \"\"\"Gets executed after mxdev read operation.\"\"\"\n\n def write(self, state: State) -> None:\n \"\"\"Gets executed after mxdev write operation.\"\"\"\n```\n\nThe default settings section from the INI file is available at `state.configuration.settings`.\nThe package configuration is available at `state.configuration.packages`.\nHook-related config sections are available at `state.configuration.hooks`.\n\nThe hook must be registered as an entry point in the `pyproject.toml` of your package:\n\n```TOML\n[project.entry-points.mxdev]\nhook = \"myextension:MyExtension\"\n```\n\n## Rationale\n\n### Problem\n\nThere is a constraint file like `-c constraints.txt` with a package `foo.bar` with a version pin.\nThen it is not possible to install this package in a requirements file editable like `-r requirements.txt` with `-e git+ssh://git@github.com/orga/foo.bar.git@fix-99`.\nNeither it is possible to override inherited version constraints with custom ones.\n\n### Idea\nA pre-processor fetches (as this can be an URL) and expands all `-c SOMEOTHER_FILE_OR_URL` and `-r SOMEOTHER_FILE_OR_URL` files into one, filtering out all packages given in a configuration file.\nFor each of those packages, a `-e ...` entry is generated instead and written to a new `TARGET.txt`.\nSame is true for version overrides: a new entry is written to the resulting constraints file while the original version is disabled.\nThe configuration is read from a file `mx.ini` in *ExtendedInterpolation* INI syntax (YAML would be nice, but the package must have as less dependencies as possible to other packages).\n\n### Trivia\nMx (generally pronounced like mix [m\u026aks], or [m\u0259ks] in the UK) is meant to be a gender-neutral alternative to the titles Mr. and Ms. but also associates with the word \"mix\".\n\n## Misc\n\nThe VCS-related code is taken from `mr.developer`.\nThanks to Florian Schulze and Contributors.\n\n## Contributing\n\nIf you want to help with the development (improvement, update, bug-fixing, ...) of `mxdev` this is a great idea!\n\nThe code is located in the [GitHub MXStack Organization / mxdev](https://github.com/mxstack/mxdev).\n\nYou can fork it, work on the project and create a pull request.\n\nMaintainers are Jens Klein and the [BlueDynamics Alliance](https://bluedynamics.com) developer team.\n\nWe appreciate any contribution! If you have an idea, found a bug, want to drop us a question, or a release is needed, please just file an issue at the [mxdev issue tracker](https://github.com/bluedynamics/mxdev/issues).\n\n## Changes\n\n## 4.0.2 (2024-03-13)\n\n- Fix #42: deprecated use of `pkg_resoures` to load entry points and parse requirements.\n This enables mxdev to work on Python 3.12, where `pkg_resources` is no longer installed by default in virtual_envs.\n [jensens]\n\n## 4.0.1 (2024-03-01)\n\n- Fix specifying out a revision (#40)\n [pbauer]\n\n### 4.0.0 (2024-02-28)\n\n- Breaking: Remove `--pre` on sources from generated `requirements-mxdev.txt`.\n Usually it is not needed any longer, at least withy pip 23.x.\n This is a breaking change if you rely on the `--pre` option being present in the generated file.\n Now the `--pre` option should be added to `pip install` when the generated file is used.\n This change enables the use of the generated file with the alternative pip replacement `uv`.\n [jensens]\n\n- Breaking: Drop official support for Python 3.7 (it is end of life).\n [jensens]\n\n- Document `mx.ini` sections `vcs` setting.\n [jensens]\n\n### 3.1.0 (2023-12-10)\n\n- Feature: Provide `directory` default setting [rnix]\n- Feature: Include other INI config files [jensens]\n\n### 3.0.0 (2023-05-08)\n\n- Removed leftover print [jensens]\n\n### 3.0.0b3 (2023-04-23)\n\n- Fix usage of `--install-option='pre'` and use `--pre` option in requirements files instead.\n The install options are deprecated in pip 23 which Plone switched to recently.\n More info:\n https://github.com/pypa/pip/issues/11358\n https://discuss.python.org/t/passing-command-line-arguments-to-pip-install-after-install-options-deprecation/22981/6\n [thet, fredvd]\n\n- Fix reading sections from the config parser without defaults if the section contains a setting that also exists as default.\n [rnix]\n\n- Do not write constraints out to the file if no constraints are defined.\n [rnix]\n\n- Add the `main-package` option to the settings.\n [rnix]\n\n### 3.0.0b2 (2023-02-07)\n\n- In this package, use `pyproject.toml` and markdown for README et al.\n [jensens]\n\n- Add `use` option to sources, and `default-use` to the settings.\n `default-use` is true by default.\n When false, the source is not checked out, and the version for this package is not overridden.\n [maurits]\n\n\n### 3.0.0b1 (2022-11-21)\n\n- Do not use `libvcs`, but recycled and updated (type hints, tests) `mr.developer` VCS code.\n Code for GIT is tested well, code for SVN, Mercurial, Bazaar and DARCS needs contributors with knowledge in this area.\n Additional options, like `pushurl`, ... (see README) were added.\n `pip` style VCS URLs are not supported any longer.\n [jensens, rnix, zworkb]\n\n- Config parser options are now considered case-sensitive.\n [rnix]\n\n- Do not fail `mxdev` run if `requirements.txt` is missing.\n [rnix]\n\n- Add flag to only fetch repositories and skip generating files.\n [rnix]\n\n- Add flag to skip fetching of repositories.\n [rnix]\n\n- Add support for custom hooks.\n [rnix]\n\n- Rename `sources.ini` to `mx.ini` in the documentation.\n [rnix]\n\n- Introduce state object and pass it to read/fetch/write.\n State object contains all required runtime data.\n [rnix]\n\n\n### 2.0.0 (2022-01-31)\n\n- Depend on pip 22, where interdependency mode is no longer needed.\n Remove all interdependency-related code.\n [jensens]\n\n- Better error message if the requirements-in file does not exist.\n [jensens]\n\n- Better last message with the full pip command.\n [jensens]\n\n- Allow empty `requirements-in` configuration.\n [jensens]\n\n### 1.1.0 (2021-12-29)\n\n- Feature: Ignore existing constraints.\n New setting `ignores` with a list of packages (one per line) to ignore constraints without providing a version.\n [jensens]\n\n\n### 1.0.1 (2021-12-21)\n\n- Fix: If a developed package depends on another developed package the dependent package was ignored *sometimes* (!?).\n Instead, the last release was taken.\n Solution: Install it with the `--pre` option in order to allow the other non-final/in-development *release*.\n [jensens]\n\n\n### 1.0.0 (2021-12-12)\n\n- Defaults for \"outfiles\" are `*-mxdev.txt` now.\n [jensens]\n\n\n### 1.0.0b4 (2021-12-07)\n\n- Fix interdependency mode.\n [jensens]\n\n\n### 1.0.0b3 (2021-12-07)\n\n- Fix: Do not apply override disabling on requirements.\n [jensens]\n\n\n### 1.0.0b2 (2021-12-07)\n\n- Add feature: version overrides.\n [jensens]\n\n\n### 1.0.0b1 (2021-12-04)\n\n- Add `-s` or `--silent` option.\n [jensens]\n\n- Beautified output.\n [jensens]\n\n- Fixed missing CR if `*.txt` does not end with a newline.\n [jensens]\n\n\n### 1.0.0a9 (2021-12-01)\n\n- Added auto correction for pip URLs, so that GitHub or GitLab URLs can be used as copied in `sources.ini`.\n [zworkb]\n\n\n### 1.0.0a8 (2021-11-30)\n\n- Added interdependency handling to avoid manual dependency order resolution.\n [jensens, gogobd]\n\n- Added skip mode to exclude packages from installation (clone/update only).\n [jensens, gogobd]\n\n- Removed position feature.\n [jensens, gogobd]\n\n\n### 1.0.0a7 (2021-11-30)\n\n- Removed Workaround for libvcs and depend on libvcs>=0.10.1.\n [jensens]\n\n\n### 1.0.0a6 (2021-11-30)\n\n- Workaround for libvcs bug https://github.com/vcs-python/libvcs/issues/295\n [jensens, gogobd]\n\n\n### 1.0.0a5 (2021-11-30)\n\n- Workaround for libvcs bug https://github.com/vcs-python/libvcs/issues/293\n [jensens, gogobd]\n\n\n### 1.0.0a4 (2021-11-29)\n\n- Fix: editable can be configured to be processed before or after initial requirements.\n [jensens]\n\n\n### 1.0.0a3 (2021-11-23)\n\n- Fix #1: Re-run of pip vanishes committed changes\n [jensens]\n\n\n### 1.0.0a2 (2021-11-21)\n\n- Fix/simplify packaging.\n [jensens]\n\n- Implement subdirectory editable install\n [jensens]\n\n- Implement package extras\n [jensens]\n\n\n### 1.0.0a1 (2021-11-21)\n\n- Initial work.\n [jensens]\n\n## License\n\nCopyright (c) 2022-2023, mxstack Contributors\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice, this\n list of conditions and the following disclaimer in the documentation and/or\n other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR\nANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND\nON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n",
"bugtrack_url": null,
"license": "BSD 2-Clause License",
"summary": "Enable to work with Python projects containing lots of packages, of which you only want to develop some.",
"version": "4.0.2",
"project_urls": {
"Bug Reports": "https://github.com/mxstack/mxdev/issues",
"Homepage": "https://github.com/mxstack/mxdev",
"Source": "https://github.com/mxstack/mxdev/"
},
"split_keywords": [
"pip",
"vcs",
"git",
"development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "74a921d56eff35e2a34d3531f55e7222d077672557440b1970f0afc14abd6a19",
"md5": "5c3ebeae24f5fc87667ecfd62ffeccd9",
"sha256": "7baf1bb45a936ff717e487b5e156d0a393d86d35e3b47d6c33f80de9642be62b"
},
"downloads": -1,
"filename": "mxdev-4.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c3ebeae24f5fc87667ecfd62ffeccd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 47053,
"upload_time": "2024-03-12T23:45:53",
"upload_time_iso_8601": "2024-03-12T23:45:53.415422Z",
"url": "https://files.pythonhosted.org/packages/74/a9/21d56eff35e2a34d3531f55e7222d077672557440b1970f0afc14abd6a19/mxdev-4.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "383d7ebf5031d14146f28fabda056bb54f7df74fb76e1df4558854f5598a383e",
"md5": "41feaad560aaa120776429e582d6540d",
"sha256": "4f978fb05460480f824040c77551b25bcf5510b8409522eac6cddc91a4ea534d"
},
"downloads": -1,
"filename": "mxdev-4.0.2.tar.gz",
"has_sig": false,
"md5_digest": "41feaad560aaa120776429e582d6540d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 43918,
"upload_time": "2024-03-12T23:45:55",
"upload_time_iso_8601": "2024-03-12T23:45:55.474822Z",
"url": "https://files.pythonhosted.org/packages/38/3d/7ebf5031d14146f28fabda056bb54f7df74fb76e1df4558854f5598a383e/mxdev-4.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-12 23:45:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mxstack",
"github_project": "mxdev",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "mxdev"
}
