Documentation#
Overview#
This is the official documentation written for the referenced release version of the Courier Package Manager. Here you will find formatted descriptions of the source code. This documentation references all functions and classes in the Courier source code and goes into detail on their purpose, functionality and associated data.
Courier.courier#
This module handles user input.
- copyright:
2023 by Joshua Rose.
- license:
MIT, see LICENSE for more details.
- class courier.Courier[source]#
Handles user input and file IO.
- add_bashrc_alias()[source]#
Eliminates need for ‘python’ prefix before file
This function also removes the need for a ‘.py’ suffix when calling courier.py. This alias references the src directory such that ‘src’ is the working directory upon runtime. Courier will not work without this as multiple path locations and tests are configured around ‘src’ being the working runtime directory.
- static assert_file_path()[source]#
Assert if file path is set to the root directory name.
- Returns:
Boolean the root directory has been set.
- static bashrc_exists()[source]#
Locate (if present) the user bash configuration file.
- This function tests under the following directories:
home/<user>/ home/<user>/dotfiles/
- Returns:
pathlib.Path
objectLiteral
boolean
- static print_formatted_list(lines)[source]#
Print list as a paragraph.
- Parameters:
lines – List of strings removed of escape characters.
- static proc_args(args, get_test=False)[source]#
Process given command line arguments when Courier is called.
- Parameters:
args – List of CLI arguments, called through sys.argv()
Courier.util.package#
This module holds the Package class which is used as a part dataclass part syntax convention to execute both utility and core methods.
- copyright:
2023 by Joshua Rose.
- license:
MIT, see LICENSE for more details.
- class util.package.Package(li, search_term)[source]#
Basic container for both singular and compound packages. Package regulates global package functions and reades files etc. Packages are often least used in a multi-instance context which is likely noticeable from the amount of staticmethods.
- static auto_install(root='.')[source]#
Read all non-local imports root recursively.
This function reads all files recursively while excluding specified folders which are set as exclusions.
- static color_path(path='/home/Josh/Documents/Programming/Courier')[source]#
Changes the color of each folder in path relative to a list preset of colors.
- Parameters:
path – (optional) Path as string which must contain at least two directories.
- Returns:
A list of path components that are then concatenated.
- Return type:
- static format_results(soup, package)[source]#
Sort a given html element and convert into parseable format.
- Parameters:
soup – BeautifulSoup html element to be sorted through.
package – A given package to be added to list Package.packages
- Returns:
If the given soup has the ‘select’ attribute.
- Return type:
- static get_date_from_lxml(lxml: BeautifulSoup)[source]#
Returns mutable BeautifulSoup object from a specified HTML class.
- Parameters:
lxml – Data structure representing an HTML element as a BeautifulSoup object
- Returns:
BeautifulSoup tag that is part of a parse tree
- Return type:
BeautifulSoup
- static get_desc_from_lxml(lxml)[source]#
Returns mutable BeautifulSoup object from a specified HTML class.
- Parameters:
lxml – Data structure representing an HTML element as a BeautifulSoup object
- Returns:
BeautifulSoup tag that is part of a parse tree
- Return type:
BeautifulSoup
- static get_name_from_lxml(lxml)[source]#
Returns mutable BeautifulSoup object from a specified HTML class.
- Parameters:
lxml – Data structure representing an HTML element as a BeautifulSoup object
- Returns:
BeautifulSoup tag that is part of a parse tree.
- Return type:
BeautifulSoup
- static get_version_from_lxml(lxml: BeautifulSoup)[source]#
Returns mutable BeautifulSoup object from a specified HTML class.
- Parameters:
lxml – Data structure representing an HTML element as a BeautifulSoup object
- Returns:
BeautifulSoup tag that is part of a parse tree
- Return type:
BeautifulSoup
- static handle_query_input(selected, unittest)[source]#
An indicator of whether a package is to be installed.
- Parameters:
selected – A python dependency parsed as a String or ID.
unittest – Boolean value used as coverage.
- Returns:
If a package is to be installed based on shown criteria.
- Return type:
- static id_from_name(name)[source]#
Compare package name to name.
Only returns package ID if package name and name are equal.
- static install_from_id(id, unittest)[source]#
Install a package from given list.
This function matches the id parameter to a given package that has been listed. It does this through the Package.name_from_id method. This can also be done in the opposite way as Package.id_from_name.
- Parameters:
id – An integer of a listed package.
unittest – Boolean in the case of unit testing.
- classmethod list()[source]#
Display packages fetched from pypi with syntax formatting.
- Parameters:
limit – The maximum amount as an Integer of packages to be displayed
- Returns:
The success state of the function
- Return type:
- static name_from_id(id)[source]#
Compare package ID to id.
Only returns package name if package id and the packge id are equal.
- static package_info(selector)[source]#
Get package info from pypi.
- Parameters:
selector – If str then get the package name, if int then get the id of
the last cached search. Note that str is mandatory if previous cache has been cleared.
- static query_install(unittest)[source]#
Query the install ID of a given package.
the package.Packages.packages (list) variable, the user may query an associated (int) ID to install a package which is converted to a string in ai Package class method.
- Parameters:
unittest – Boolean value used as coverage
- Returns:
If exception caught from user input
- Return type:
- static query_install_input(unittest)[source]#
Query user input to select package to install.
- Parameters:
unittest – Boolean value used in case of coverage.
- Returns:
The user selected package ID from displayed packages.
- Return type:
- static request_pypi(package)[source]#
Request an HTTP response for package
- Parameters:
package – A URL of a python package, typically matching that of a pypi package url.
- Returns:
Server response to requested URL package
- Return type:
requests.Response
- static request_pypi_soup(package)[source]#
Requests a soup object from a pypy package URL.
- Parameters:
package – A URL of a python package, typically matching that of a pypi package url.
- Returns:
BeautifulSoup data structure representing an html element.
- Return type:
BeautifulSoup
- static search(package, unittest=False)[source]#
Search for package in the pypi database.
- Parameters:
package – Package name as string.
activate_test_case – (optional) Used for unit test coverage.
- Returns:
If search yields results (which is most of the time will)
- Return type:
- static service_online(url='https://pypi.org')[source]#
This function checks if the specified URL is online.
- Parameters:
url – URL String to be used as a request object.
- Returns:
Status code of request matches online status code (200)
- Return type:
Courier.util.codescan#
Scans python files for unsatisfied imports.
Codescan [verb] (my definition): To scan code for unmet dependencies. Codescan [noun] (my definition): A report of unmet dependencies.
- copyright:
2023 by Joshua Rose.
- license:
MIT, see LICENSE for more details.
TODO: codescan configuration file
- class util.codescan.Codescan[source]#
Hold methods pertaining to the codescan function.
BUG: Some modules are not included, despite being present in project. TODO: Optimize local_modules such that only working modules are called.
- classmethod install_dependencies()[source]#
Install previous dependencies collected from scan.
The scan is run within the install_dependencies method.
- classmethod scan()[source]#
Scan for imports in collected files.
Calls Package.auto_install() to fetch files matching a given regex. scan() then recursively iterates through fetched files and extracts imports. Imports are then validated in install_dependencies() to ensure that they meet the criteria for external dependencies.
Courier.util.setup#
This module contains utility function(s) that are used for formatting and general aethetics.
- copyright:
2023 by Joshua Rose.
- license:
MIT, see LICENSE for more details.
- util.setup.escape_ansi(line) str [source]#
Remove formatting from colored string
credit: Édouard Lopez
- Parameters:
line – Colored string with escape characters
- Returns:
string with escape characters removed
- Return type:
string
- util.setup.get_date(date: datetime, day='13') str [source]#
Return a ❇️ colorized ❇️ version of timestamp
- Parameters:
date – timestamp as a datetime.datetime instance
day – (optional) String of current day without x0 format
- Returns:
Formatted string of the current date
- Return type:
string
Courier.util.update#
This modules is reponsible for updating Courier as a program. This module is also responsibile for utility functions and the management of aesthetic dependencies such as colorama and logging.
- copyright:
2023 by Joshua Rose.
- license:
MIT, see LICENSE for more details.
- util.update.create_package()[source]#
Dump json object to PACKAGE.
create_package() raises a permission error if the user does not have write permissions to current working directory.
- util.update.file_exists(file, mode)[source]#
Test if file exists in the current working directory.
- Parameters:
file – Filename as a string
mode – Given filemode eg: read, write, append (as str)
- Returns:
False if file is not present or TextIOWrapper if present
- Return type:
- util.update.get_package_name()[source]#
Get package name.
Note that this function also allows for unit tests.
- Returns:
A directory entry of the current file.
- Return type:
- util.update.get_project_folder()[source]#
Dedicated function for testing.
- Returns:
The base-name of of the current project folder.
- Return type:
- util.update.last_updated()[source]#
Last update in datetime format.
- This is assuming that
>>> if project_folder != 'Courier': os.chdir('..')
has run as this function is dependant on the current working directory containing the PACKAGE file.
- Returns:
Current date as a datetime object.
- Return type:
- util.update.load_logging_ini(config='config_info.ini')[source]#
Load logging configuration file.
- Parameters:
config – Configuration file as str.
- util.update.loc_package_file(name=<DirEntry 'update.json'>, debug=False, mode='r')[source]#
Locate the package file & create package file
If the file does not exist it will be created in the current working directory of wherever courier.py was called from.
- Parameters:
name – DirEntry of current package name as file
debug – If a unit test is to be conducted allow for artifically invoked edge cases.
mode – Edit mode of file to be called as read, write or append.
- Returns:
File object if package has been opened or None
- Return type:
FileIOWrapper
- util.update.scan_dir(files=True, folders=True)[source]#
A better version of the os.scandir function, as it takes multiple args.
- Parameters:
files – (optional) List files in current directory
folders – (optional) List folders in current directory
- Returns:
A list of current files and folders found
- Return type:
list[DirEntry]