Developer Interface

Developer Interface#

Main Interface#

Examples for the most relevant api functions can be viewed in the test file. fpyutils’s API uses type hints instead of assertions to check input and output types.

fpyutils.filelines.get_line_matches(input_file: str, pattern: str, max_occurrencies: int = 0, loose_matching: bool = True, keep_all_lines: bool = False) → tuple[dict[int, int], str]#

Get the line numbers of matched patterns and the matched string itself.

Parameters:

  • input_file (str) – the file that needs to be read.

  • pattern (str) – the pattern that needs to be searched.

  • max_occurrencies (int) – the maximum number of expected occurrencies. Defaults to 0 which means that all occurrencies will be matched. This parameter is limited by the platform (sys.maxsize).

  • loose_matching (bool) – ignore leading and trailing whitespace characters for both pattern and matched strings. Defaults to True.

  • keep_all_lines (bool) – if set to True returns the whole file content as a string. Defaults to False.

Returns:

occurrency_matches, a dictionary where each key corresponds to the number of occurrencies and each value to the matched line number. If no match was found for that particular occurrency, the key is not set. This means means for example: if the first occurrency of pattern is at line y then: x[1] = y, with x being the dictionary.

lines, a string corresponding to the matched lines or the whole file (see keep_all_lines argument).

Return type:

tuple[dict[int, int], str]

Raises:

a built-in exception.

Note

Line numbers start from 1.

fpyutils.filelines.insert_string_at_line(input_file: str, string_to_be_inserted: str, put_at_line_number: int, output_file: str, append: bool = True, newline_character: str = '\n')#

Write a string at the specified line.

Parameters:

  • input_file (str) – the file that needs to be read.

  • string_to_be_inserted (str) – the string that needs to be added.

  • put_at_line_number – the line number on which to append the string.

  • output_file (str) – the file that needs to be written with the new content.

  • append (bool) – decides whether to append or prepend the string at the selected line. Defaults to True.

  • newline_character (str) – set the character used to fill the file in case line_number is greater than the number of lines of input_file. Defaults to the default platform newline, i.e: os.linesep.

Returns:

None

Raises:

a built-in exception.

Note

Line numbers start from 1.

Note

Existing line endings of the input file are changed to newline_character.

fpyutils.filelines.remove_line_interval(input_file: str, delete_line_from: int, delete_line_to: int, output_file: str)#

Remove a line interval.

Parameters:

  • input_file (str) – the file that needs to be read.

  • delete_line_from (int) – the line number from which start deleting.

  • delete_line_to (int) – the line number to which stop deleting.

  • output_file (str) – the file that needs to be written without the selected lines.

Returns:

None

Raises:

NegativeLineRangeError, LineOutOfFileBoundsError or a built-in exception.

Note

Line numbers start from 1.

Note

It is possible to remove a single line only. This happens when the parameters delete_line_from and delete_line_to are equal.

fpyutils.shell.execute_command_live_output(command: str, shell: str = '/bin/bash', dry_run: bool = False, output_character_encoding: str = 'UTF-8') → int#

Execute and print the output of a command relatime.

Parameters:

  • command (str) – the shell commands that needs to be executed.

  • shell (str) – the shell binary that will be used to execute the command. Defaults to /bin/bash.

  • dry_run (bool) – print the command instead of executing it. Defaults to False.

  • output_character_encoding (str) – the character encoding of the output. Defaults to UTF-8.

Returns:

process.returncode, the return code of the executed command.

Return type:

int

Raises:

a subprocess, sys or a built-in exception.

fpyutils.path.add_trailing_slash(uri: str) → str#

Add a trailing slash when needed.

Parameters:

uri (str) – a string, usually an URI.

Returns uri:

the input string with a trailing slash.

Return type:

str

Raises:

a built-in exception.

fpyutils.path.gen_pseudorandom_path(path_suffix: str = '', date_component_format: str = '%F_%H-%M-%S_%f', component_separator: str = '_', pseudorandom_component_bytes: int = 4, hash_component_digest_size: int = 3, character_encoding: str = 'UTF-8') → str#

Generate a pseudorandom string useful for paths.

Parameters:

  • path_suffix (str) – the final part of the string. Defaults to str().

  • date_component_format (str) – the format of the date component. Defaults to %F_%H-%M-%S_%f.

  • component_separator (str) – an element that separates the various components. Defaults to _.

  • pseudorandom_component_bytes (int) – the number of bytes of the pseudorandom components. Defaults to 4.

  • hash_component_digest_size (int) – the digest size of the hashed component. Defaults to 3.

  • character_encoding (str) – the character encoding of the hashed component. Defaults to UTF-8.

Returns:

Return type:

str

Raises:

a built-in exception.

Note

This system minimises the risk of collisions for creating a path.

fpyutils.notify.send_email(message: str, smtp_server: str, port: int, sender: str, user: str, password: str, receiver: str, subject: str) → dict#

Send an email.

Parameters:

  • message (str) – the body of the message.

  • smtp_server (str) – the address of the sending server.

  • port (int) – the port of the sending server.

  • sender (str) – the email of the sender.

  • user (str) – the username of the sender.

  • password (str) – the password of the sender.

  • receiver (str) – the email of the receiver.

  • subject (str) – the subject field of the email.

Returns:

an empty dictionary on no error, otherwise an exception is raised.

Return type:

dict

Raises:

a built-in exception.

fpyutils.notify.send_gotify_message(url: str, token: str, message: str = 'message', title: str = 'title', priority: int = 5)#

Send a notification to a gotify server.

Parameters:

  • url (str) – the URL of the Gotify server

  • token (str) – the APP token

  • message (str) – the message title. Defaults to message.

  • title (str) – the text of the message Defaults to title.

  • priority (int) – the message priority. Defaults to 5.

Returns:

a http.client.HTTPResponse object

Raises:

ValueError or a built-in exception.

Exceptions#

exception fpyutils.exceptions.LineOutOfFileBoundsError#

Line out of bounds.

Raises an exception if there was an attempt to access a non-existing line in a file.

exception fpyutils.exceptions.NegativeLineRangeError#

Line range does not make sense.