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

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.

  • 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

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

LineOutOfFileBoundsError or a built-in exception.

Note

Line numbers start from 1.

Note

Exsisting 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

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.

Raises

a requests or a built-in exception.

Exceptions

exception fpyutils.LineOutOfFileBoundsError

Line out of bounds.

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

exception fpyutils.NegativeLineRangeError

Line range does not make sense.