devutils package¶
Submodules¶
changehandler module¶
-
class
crl.devutils.changehandler.
ChangeHandler
(run, pathtochangefile=None)[source]¶ Validates the given change file’s syntax and parses the change file to get the latest documented version. If the change file isn’t specified, it looks for a file named ‘CHANGES’ on the package’s root directory and uses it. Valid file extensions for change file are ‘.rst’ and ‘.md’.
Parameters: - run – Reference to a function capable of running shell commands.
- pathtochangefile – Relative path to change file.
-
change_file
¶ Name/Relative path of change file in use.
-
latest_version
¶ The latest version as in Change file.
-
verify
(version)[source]¶ Verify if the given version is the newest version listed in ChangeFile.
Parameters: version – version to check.
Raises: Failure
– Raised if the Change file syntax is incorrect.ChangeFileNotFound
– Raised if the Change file is not found.MultipleChangeFilesFound
– Raised if more than one changefile found.ChangeFileVersionCheckFailed
– Raises if the given version is not the newest version listed in the Changefile.
devpihandler module¶
-
class
crl.devutils.devpihandler.
DevpiHandler
(run, packagehandler, credentials_file=None)[source]¶ A handler for handling all devpi related actions.
Parameters: - run – Reference to a function capable of running shell commands.
- packagehandler – An instance of PackageHandler object
- credentials_file – User login information in a file.
-
create_index
(name, baseindex, otherbase=None, credentials_file=None)[source]¶ Create a new index for the current user with given bases.
Parameters: - name – Name of the index to create, specified as NAME.
- baseindex – URL of index from which the new index will inherit.
- otherbase – Name of other indices (specified as USER/NAME) to use.
- credentials_file – File containing the users credentials.
-
delete_index
(index, credentials_file=None)[source]¶ Delete the given index.
Parameters: index – Index to delete, specified as http[s]://host/user/index.
-
index
¶ Currently used PyPI index.
-
latest_pypi_version
(pkg_name=None, pypi_index=None)[source]¶ Returns latest version of a package from the given index.
Parameters: - pkg_name – Name of the package, if different from the current package.
- pypi_index – Name of the index, if different from the current index.
-
publish
(index)[source]¶ Publish a version of package from current index to given index.
Parameters: index – PYPI Index to publish to.
-
set_index
(index)[source]¶ Set the given index as the current index.
Parameters: index – Index, specified as http[s]://host/user/index. Raises: MalformedURL
– If index URL is in wrong format.
-
test
(test_index=None)[source]¶ Test and upload results and docs to the given index. If no index is specified, uses a temporary index.
Parameters: test_index – Index name to use for testing, specified as NAME.
-
url
¶ //host
Type: The base URL of the PYPI server, specified as http[s]
-
userindex
¶ Current user index, specified as user/indexname
-
username
¶ Currently logged in username. If no user is logged in, uses credentials from a file.
githandler module¶
-
class
crl.devutils.githandler.
GitHandler
(run)[source]¶ A handler responsible for handling all git related actions.
Parameters: run – Reference to a function capable of running shell commands. -
checkout
(filename)[source]¶ Checks out the given filename
Parameters: filename – Name of the file to checkout.
-
clone
(gitrepo, version)[source]¶ Clone and checkout the given version of git repository.
Parameters: - gitrepo – URL of the git project.
- version – Git version to checkout.
-
clone_or_update
(gitrepo, version)[source]¶ If not already cloned, clones the version to a local directory. If cloned already, updates the local directory with given version.
Parameters: - gitrepo – URL of the git project.
- version – Git version to clone or update.
-
commit
(paths, message, push=False)[source]¶ Commits given file with given message and optionally pushes to remote.
Parameters: - paths – Path of file(s) to be committed.
- message – Commit message.
- push – If or not to push the commit to remote.
Returns: True, if all commands succeded
Return type: bool
-
get_branch_of_tag
(tag)[source]¶ Get the branch which contains the given tag.
Parameters: tag – Tag to look for.
-
is_clean
()[source]¶ Checks if current working directory is clean.
Returns: True, if directory is clean. Return type: bool
-
tag_release
(version, push)[source]¶ Tags a given version if not already tagged and optionally pushes all tags to remote.
Parameters: - version – Version to tag.
- push – If or not to push the tags to remote.
Returns: True, if all commands succeded, False, if any of them failed.
Return type: bool
-
update
(gitrepo, version)[source]¶ Update the local working directory with the given version if the local working directory is clean.
Parameters: - gitrepo – URL of the git project.
- version – Git version to checkout.
-
update_version
(version, version_file, push)[source]¶ Updates the given version file with a given version, commits and optionally pushes to the remote.
Parameters: - version – Version to update.
- version_file – Name or Path of the version file.
- push – If or not to push the commit to remote.
-
verify_clean
()[source]¶ Checks if or not, the current working dirctory is clean.
Raises: UncleanGitRepository
– If the current working directory is unclean.
-
packagehandler module¶
-
class
crl.devutils.packagehandler.
PackageHandler
(versionhandler, setuphandler, changehandler, githandler, novirtualenv=False)[source]¶ A handler for handling operations on a package.
Parameters: - versionhandler – An instance of VersionHandler.
- setuphandler – An instance of SetupHandler.
- changehandler – An instance of ChnageHandler.
- githandler – An instance of GitHandler.
- novirtualenv – If or not virtualenv must be used.
-
publish
(srcindex, destindex, credentials_file=None, tag_if_needed=False, tag_branch='master')[source]¶ Performs pre-checks and prepares for package version to be published from a given index to another.
Parameters: - srcindex – Index from where to find the package version.
- destindex – Index to publish the package version.
- credentials_file – User credentials to use.
- tag_if_needed – If or not to tag the version, if not tagged already.
- tag_branch – Alternative git branch where the tag must be found.
Returns: - True, if publish was successful and False if publish was
skipped as package version was already published to destindex.
Return type: bool
Raises: VersionTagInWrongBranch
– Tag was found in a different branch.ChangeFileVersionCheckFailed
– Change file version doesn’t match with the package version.UncleanGitRepository
– If the working directory is found unclean.MismatchOfTagAndSetupVersion
– If there is a mismatch in tag and setup versions.
-
tag_release
(version, push)[source]¶ Updates the version file and tags with the specified version and optionally pushes to the remote git repository.
Parameters: - version – Version with which the version file must be updated and remote git tag must be created.
- push – If TRUE, commits version file and pushes the tag to git.
Raises: ChangeFileVersionCheckFailed
– Change file version doesn’t match with the package version.
-
test
(base_index, test_index=None, credentials_file=None, save_tests_to=None)[source]¶ Runs tests and uploads the results and docs to a given index. If no index is given, a temporary index which is created for running tests is later deleted.
Parameters: - base_index – Index to be used as a base for the test index, specified as http[s]://host/user/index.
- test_index – Name of the index created for testing, specified as NAME.
- credentials_file – User credentials to use.
- save_tests_to – If given, copies the temporary files generated during testing to this path.
Raises: ChangeFileVersionCheckFailed
– Change file version doesn’t match with the package version.
-
update_version
(version, push)[source]¶ Updates the version file with the specified version and optionally commits and pushes the file to the remote git repository.
Parameters: - version – Version with which the version file must be updated.
- push – If TRUE, commits and pushes the version file to git.
-
verify_clean
()[source]¶ Verifies the cleanliness/readyness of the package before any actions are performed on the package. Following are checked 1. Version file consistency. 2. Change file consistency. 3. Clean working directory. 4. Tag existence and its branch.
Raises: VersionTagInWrongBranch
– Tag found in wrong branch.MismatchOfTagAndSetupVersion
– Tag and setup version are different.InvalidVersionValue
– Version in incorrect format.ChangeFileNotFound
– Change file doesn’t exist.MultipleChangeFilesFound
– More than one change files are found.ChangeFileVersionCheckFailed
– Change file’s latest version is not same as package’s setup version.UncleanGitRepository
– Working directory is unclean.
runner module¶
-
crl.devutils.runner.
run
(cmd, replaced_output=None, shell=True, verbose=False, env=None, ignore_codes=None)[source]¶ Run shell command and return Result object.
Parameters: - cmd – Command to be executed.
- replaced_output – Replace stdout with replaced_output and return empty stderr.
- shell – If or not, the given command must be executed through the shell.
- verbose – If or not, task execution must be displayed in more detail.
- env – Environment defining any variables needed for the new process.
- ignore_codes – A list of exit codes that the command must ignore.
Raises: Failure
– If the command exited with exit code greater than zero and it is not in list of ignore codes.
setuphandler module¶
versionhandler module¶
-
class
crl.devutils.versionhandler.
VersionHandler
(libname=None, pathtoversionfile=None)[source]¶ Version handler for ./src/crl/<libname>/_version.py`.
Version can have these values: - Actual version number to use. See below for supported formats. - String ‘dev’ to update version to latest development version (e.g. 2.8 -> 2.8.1.dev, 2.8.1 -> 2.8.2.dev, 2.8a1 -> 2.8.dev) with the current date added or updated.
Given version must be in one of these PEP-440 compatible formats: - Stable version in ‘X.Y’ or ‘X.Y.Z’ format (e.g. 2.8, 2.8.6) - Pre-releases with ‘aN’, ‘bN’ or ‘rcN’ postfix (e.g. 2.8a1, 2.8.6rc2) - Development releases with ‘.devYYYYMMDD’ postfix (e.g. 2.8.6.dev20141001) or with ‘.dev’ alone (e.g. 2.8.6.dev) in which case date is added automatically.
Parameters: - libname – Name of the library.
- pathtoversionfile – Relative path to the version file.