poetic.util module¶

Module for package utility.

This module includes the necessary functionalities to load and download assets for other modules in the package and provide basic information for the current build and version as needed.

Examples

To get the build and version information of the package:

import poetic

poetic.util.Info.version()
poetic.util.Info.build_status()

Under normal circumstances, the methods in the Initializer class is not needed as part of the prediction workflow. One of the most common usage of a first-time user is to download the assets:

import poetic

poetic.util.Initializer.download_assets()

The tensorflow model and gensim models can also be loaded and returned if they theselves are useful (the Predictor class loads the model automatically):

import poetic

poetic.util.Initializer.load_dict()
poetic.util.Initializer.load_model()

Both download_assets() and load_model() methods have the force_download parameter which controls whether to download the models without taking commandline inputs when the model is missing. It is default to False so that it does not take up bandwidth unintendedly, but it can also be set to True in cases necessary.

class poetic.util.Info(_test: Optional[bool] = False)¶

Bases: object

Basic information for the package.

Info class provides the basic information of the package: its version and build status. This class, by design, is a singleton and has no public interface.

Raises: poetic.exceptions.SingletonError – This exception is raised when an instance of the Info class already exists while calling the constructor.

classmethod build_status() → str¶

A getter method to return build status of the current version.

Returns: The build status of the current version.
Return type: str

classmethod get_instance(_test: Optional[bool] = False) → poetic.util.Info ¶

The method to access the singleton Info class.

The use of this method is recommended over using the constructor because the constructor will throw an exception if an instance already exists.

Returns: The singleton Info class
Return type: poetic.util.Info

classmethod version() → str¶

A getter method to return the version of the package.

Returns: The current version of the package.
Return type: str

class poetic.util.Initializer¶

Bases: object

Initializes core components of the package.

The Initializer is core part of Poetic that loads and downloads models and other necessary assets. It also facilitates the command line mode by interacting with the _Arguments class.

classmethod check_assets() → Dict[str, bool]¶

Method to check whether assets requirements are met.

This method checks both the model and its weights in the corresponding directory. It reports back their existence as part of the package requirement.

Returns: the status of the assets as a dictionary.
Return type: dict

classmethod download_assets(assets_status: Optional[Dict[str, bool]] = None, force_download: Optional[bool] = False) → None¶

Method to download models.

This method downloads models from the poetic-models github repository. Under usual circumstances, other functions will download the models automatically if needed. If all the models already exist, this function will not download them again for package efficiency and bandwidth saving.

If you would like to redownload the assets anyway, a manual download from https://github.com/kevin931/poetic-models/releases is necessary.

Parameters

assets_status (dict, optional) – A dictionary generated by check_assets() method. It has keys “all_exist”, “model”, and “weights” with all values being boolean.
force_download (bool, optional) – A boolean indicating whether assets should be downloaded regardless of their existence and user inputs.

classmethod initialize(*, _test_args: Optional[Union[List[str], str]] = None)¶

Initializes the package.

This methods checks for any command line arguments, and then loads both the gensim dictionary and the Keras model with its weights.

Returns

Tuple with the following elements

dict:
A dictionary of commandline arguments.

tensorflow.keras.Model:
A pre-trained Keras model with its weights loaded.

gensim.corpora.dictionary.Dictionary:
A gensim dictionary.

Return type

tuple

classmethod load_dict(*, dictionary_path: Optional[str] = None) → gensim.corpora.dictionary.Dictionary¶

Loads gensim dictionary.

This method loads the gensim dictionary necessary for converting word tokens into ids for preprocessing. When ‘dictionary_path’ is not provided, the method loads the default dictionary of the package; otherwise, the specified dictionary will be loaded and returned.

Parameters: dictionary_path (str, optional) – The path to the custom gensim dictionary saved using save_as_text() or a text file in the same format. File extension is not enforced.
Returns: A gensim dictionary.
Return type: gensim.corpora.dictionary.Dictionary

classmethod load_model(force_download: Optional[bool] = False, *, model_path: Optional[str] = None, weights_path: Optional[str] = None) → tensorflow.keras.Model¶

Load Keras models.

This method uses the Keras interface to load the previously trained models, which are necessary for the Predictor and the GUI. To use the default models, use all default parameters. If the default model does not exist and no custom model is provided, the download_assets() method is automatically called for the option to obtain the necessary assets. To use custom models, only Keras models saved in .json, .yaml, and .h5 are supported by this method.

Parameters

force_download (bool, optional) – A boolean value on whether to download the default models without asking if they do not exist. This parameter ignored when model_path is provided.
model_path (str, optional) – The path to the keras model file in json, yaml, or h5 format. It is optional when default models are intended. When weights_path is provided, model_path is mandatory.
weights_path (str, optional) – The path to the weights of the model to be loaded. It is optional for loading the default model or customized models saved in h5 format. It is mandatory for json or yaml model files.

Returns

Pretrained Keras model

Return type

tensorflow.keras.Model

Raises

ValueError – Errors for unsupported model_path and weights_path.