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 object Literal boolean

static close_file(file)[source]#

Closes a file for unit testing.

Parameters:: file – TextIOWrapper

static get_file_path()[source]#

Fetch immediate parent folder of current directory.

Returns:: String

get_package_created()[source]#: Format return value of the previous timestamp of update.json

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()

static read_docs(file='help.txt')[source]#

Read documentation file from folder.

Colored documentation is going to be added, so I’m still finding a way to implement that, however it will be done.

Parameters:: file – (optional) file from /docs as reference.
Returns:: file contents excluding escape characters.
Return type:: list[str]

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.

Parameters:: root – (optional) Root directory as string.
Returns:: A list of files that match the given quota
Return type:: list[str]

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:: str

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:

bool

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:

bool

static id_from_name(name)[source]#

Compare package name to name.

Only returns package ID if package name and name are equal.

Parameters:: name – A string of the package name to get ID from.
Returns:: A string of the package name if package name is equal to name
Return type:: int | bool

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:: bool

static name_from_id(id)[source]#

Compare package ID to id.

Only returns package name if package id and the packge id are equal.

Parameters:: id – An Integer of the package ID to get name from.
Returns:: An integer of the package ID if package ID is equal to id
Return type:: str | bool

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:: bool

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:: int

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:

bool

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:: bool

static update_cache(package)[source]#

Sends results to cache but does not display or query input

Parameters:: package – Name of package to add to cache.
Returns:: bool if no results found
Return type:: bool

static update_package(package)[source]#

Updates package to latest or specified version with pip.

Parameters:: package – A string that matches a pypi supported dependency
Returns:: Returns if the operation was successful or not in updating package.
Return type:: bool

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.

Returns:: List of import expressions extracted from Package.auto_install()
Return type:: list[str]

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:

bool

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:: bool

util.update.get_project_folder()[source]#

Dedicated function for testing.

Returns:: The base-name of of the current project folder.
Return type:: str

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:: str

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]

util.update.switch_root()[source]#

Auto switch root when not applicable.

Returns:: Full current project path as str
Return type:: str