pyphysim.progressbar package

Submodules

pyphysim.progressbar.progressbar module

Implement classes to represent the progress of a task.

Use the ProgressbarText class for tasks that do not use multiprocessing, and the ProgressbarMultiProcessServer class for tasks using multiprocessing.

Basically, the task code must call the “progress” function to update the progress bar and pass a number equivalent to the increment in the progress since the last call. The progressbar must know the maximum value equivalent to all the progress, which is passed during object creator for ProgressbarText class.

The ProgressbarMultiProcessServer is similar to ProgressbarText class, accounts for the progress of multiple processes. For each process you need to call the register_client_and_get_proxy_progressbar to get a proxy progressbar, where the maximum value equivalent to all the progress that will be performed by that process is passed in this proxy creation. Each process then calls the progress method of the proxy progressbar.

Note that there is also a DummyProgressbar whose progress function does nothing. This is useful when you want to give the user a choice to show or not the progressbar such that the task code can always call the progress method and you only change the progressbar object.

class pyphysim.progressbar.progressbar.DummyProgressbar(*args: Any, **kwargs: Any)

Bases: object

Dummy progress bar that don’t really do anything.

The idea is that it can be used in place of the ProgressbarText class, but without actually doing anything.

See also

ProgressbarText

progress(count: int) → None

This progress method has the same signature from the one in the ProgressbarText class.

Nothing happens when this method is called.

Parameters

count (int) – Ignored

class pyphysim.progressbar.progressbar.ProgressBarBase(finalcount: int)

Bases: object

Base class for all ProgressBar classes.

Parameters

finalcount (int) – The total amount that corresponds to 100%. Each time the progress method is called with a number that number is added with the current amount in the progressbar. When the amount becomes equal to finalcount the bar will be 100% complete.

Notes

Derived classes should implement _update_iteration() and _display_current_progress(). Optionally derived class might also implement _perform_initialization() and _perform_finalizations()

_count_to_percent(count: int) → float

Convert a given count into the equivalent percentage.

Parameters

count (int) – The current count to be represented in the progressbar. The progressbar represents this count as a percent value of self.finalcount

Returns

percentage – The percentage that count is of self.finalcount (between 0 and 100)

Return type

float

_display_current_progress() → None

Refresh the progress representation.

This method should be defined in a subclass.

_perform_finalizations() → None

Perform any finalization (cleanings) after the progressbar stops.

This method should be implemented in sub-classes if any finalization code should be run.

_perform_initialization() → None

Perform any initializations for the progressbar.

This method should be implemented in sub-classes if any initialization code should be run.

_update_iteration(count: int) → None

Update the progressbar according with the new count.

Parameters

count (int) – The current count to be represented in the progressbar. The progressbar represents this count as a percent value of self.finalcount

property elapsed_time

Get method for the elapsed_time property.

Returns

The elapsed time.

Return type

str

final progress(count: int) → None

Updates the current progress.

Calling this function will update the the current progress.

Parameters

count (int) – The current count to be represented in the progressbar. The progressbar represents this count as a percent value of self.finalcount

Notes

How the progressbar is actually represented depends on the subclass. In the subclasses implement the _update_iteration method to update the current representation of the progressbar and the _update_progress_display to actually display the current progress.

final start() → None

Start the progressbar.

This method should be called just before the progressbar is used for the first time. Among possible other things, it will store the current time so that the elapsed time can be tracked.

If is automatically called in the progress method, if not called before.

final stop() → None

Stop the progressbar.

This method is automatically called in the progress method when the progress reaches 100%. If manually called, any subsequent call to the progress method will be ignored.

class pyphysim.progressbar.progressbar.ProgressBarIPython(finalcount: int, side_message: Optional[str] = None)

Bases: pyphysim.progressbar.progressbar.ProgressBarBase

Progressbar for IPython notebooks.

The progressbar will be rendered using IPython widgets.

_display_current_progress() → None

Refresh the progress representation.

_perform_initialization() → None

Perform any initializations for the progressbar.

This method should be implemented in sub-classes if any initialization code should be run.

_update_iteration(count: int) → None

Update the self.prog_bar member variable according with the new count.

Parameters

count (int) – The current count to be represented in the progressbar. The progressbar represents this count as a percent value of self.finalcount

class pyphysim.progressbar.progressbar.ProgressbarDistributedClientBase(client_id: int, finalcount: int)

Bases: pyphysim.progressbar.progressbar.ProgressBarBase

Proxy progressbar that behaves like a ProgressbarText object, but is actually updating a shared (with other clients) progressbar.

The basic idea is that this proxy progressbar has the “progress” method similar to the standard ProgressbarText class. However, when this method is called it will update a value that will be read by a “server progressbar” object which is responsible to actually show the current progress.

Parameters

client_id (ClientID) – The client ID.

_display_current_progress() → None

Refresh the progress representation.

This method should be defined in a subclass.

_update_iteration(count: int) → None

Update the progressbar according with the new count.

Parameters

count (int) – The current count to be represented in the progressbar. The progressbar represents this count as a percent value of self.finalcount

class pyphysim.progressbar.progressbar.ProgressbarDistributedServerBase(progresschar: str = '*', message: str = '', sleep_time: float = 1.0, filename: Optional[str] = None, style='text2')

Bases: object

Base class for progressbars for distributed computations.

In order to track the progress of distributed computations two classes are required, one that acts as a central point and is responsible to actually show the progress (the server), and other class that acts as a proxy (the client) and is responsible to sending the current progress to the server. There will be one object of the “server class” and one or more objects of the “client class”, each one tracking the progress of one of the distributed computations.

This class is a base class for the “server part”, while the ProgressbarDistributedClientBase class is a base class for the “client part”.

For a full implementation, see the ProgressbarMultiProcessServer and ProgressbarMultiProcessClient classes.

Parameters

• progresschar (str) – Character used in the progressbar.

• message (str) – Message writen in the progressbar.

• sleep_time (float) – Time between progressbar updates (in seconds).

• filename (str) – If filename is None (default) then progress will be output to sys.stdout. If it is not None then the progress will be output to a file with name filename. This is usually useful for debugging and testing purposes.

• style (str) – The progressbar style. It controls which progressbar is used to display progress. It can be either ‘text1’, ‘text2’, ‘text3’, or ‘ipython’

_ProgressbarDistributedServerBase__cretae_inner_progressbar(output)

_register_client(total_count: int) → int

Register a new “client” for the progressbar and return its client_id.

These returned values must be passed to the corresponding proxy progressbar.

Parameters

total_count (int) – Total count that will be equivalent to 100% progress for the function.

Returns

client_id – The client_id. The function whose process is tracked by the ProgressbarMultiProcessServer must update the element client_id with the current count.

Return type

ClientID

_update_client_data_list() → None

This method process the communication between the client and the server.

It should gather the information sent by the clients (proxy progressbars) and update the member variable self._client_data_list accordingly, which will then be automatically represented in the progressbar.

_update_progress(filename: Optional[str] = None, start_delay: float = 0.0) → None

Collects the progress from each registered proxy progressbar and updates the actual visible progressbar.

Parameters

• filename (str) – Name of a file where the data will be written to. If this is None then all progress will be printed in the standard output (default)

• start_delay (float, optional) – Delay in seconds before starting the progressbar. During this time it is still possible to register new clients and the progressbar will only be shown after this delay..

register_client_and_get_proxy_progressbar(total_count: int) → pyphysim.progressbar.progressbar.ProgressbarDistributedClientBase

Register a new “client” for the progressbar and returns a new proxy progressbar that the client can use to update its progress by calling the progress method of this proxy progressbar.

Parameters

total_count (int) – Total count that will be equivalent to 100% for function.

Returns

obj – The proxy progressbar.

Return type

Object of a class derived from ProgressbarDistributedClientBase

start_updater(start_delay: float = 0.0) → None

Start the process that updates the progressbar.

Parameters

start_delay (float) – Delay in seconds before starting the progressbar. During this time it is still possible to register new clients and the progressbar will only be shown after this delay..

Notes

If this method is called multiple times then the stop_updater method must be called the same number of times for the updater process to actually stop.

stop_updater(timeout: Optional[float] = None) → None

Stop the process updating the progressbar.

You should always call this function in your main process (the same that created the progressbar) after joining all the processes that update the progressbar. This guarantees that the progressbar updated any pending change and exited clearly.

Parameters

timeout (float) – The timeout to join for the process to stop.

Notes

If the start_updater was called multiple times the process will only be stopped when stop_updater is called the same number of times.

property total_final_count

Get method for the total_final_count property.

Returns

The final count.

Return type

int

class pyphysim.progressbar.progressbar.ProgressbarMultiProcessClient(client_id: int, client_data_list: List[Any], finalcount: int)

Bases: pyphysim.progressbar.progressbar.ProgressbarDistributedClientBase

Proxy progressbar that behaves like a ProgressbarText object, but is actually updating a ProgressbarMultiProcessServer progressbar.

The basic idea is that this proxy progressbar has the “progress” method similar to the standard ProgressbarText class. However, when this method is called it will update a value that will be read by a ProgressbarMultiProcessServer object instead.

Parameters

• client_id (ClientID) – The client ID

• client_data_list (list) – The client data list

_update_iteration(count: int) → None

Updates the proxy progress bar.

Parameters

count (int) – The new amount of progress.

class pyphysim.progressbar.progressbar.ProgressbarMultiProcessServer(progresschar: str = '*', message: str = '', sleep_time: float = 1.0, filename: Optional[str] = None, style: str = 'text2')

Bases: pyphysim.progressbar.progressbar.ProgressbarDistributedServerBase

Class that prints a representation of the current progress of multiple process as text.

While the ProgressbarText class only tracks the progress of a single process, the ProgressbarMultiProcessServer class can track the joint progress of multiple processes. This may be used, for instance, when you parallelize some task using the multiprocessing module.

Using the ProgressbarMultiProcessServer class requires a little more work than using the ProgressbarText class, as it is described in the following:

1. First you create an object of the ProgressbarMultiProcessServer class as usual. However, differently from the ProgressbarText class you don’t pass the finalcount value to the progressbar yet.

2. After that, for each process to be tracked, call the register_client_and_get_proxy_progressbar() method passing the number equivalent to full progress for that process. This function returns a “proxy progressbar” that behaves like a regular ProgressbarText. Pass that proxy progressbar as an argument to that process so that it can call its “progress” method. Each process that calls the “progress” method of the received proxy progressbar will actually update the progress of the main ProgressbarMultiProcessServer object.

3. Start all the processes and call the start_updater method of ProgressbarMultiProcessServer object so that the bar is updated by the different processes.

4. After joining all the process (all work is finished) call the stop_updater method of the ProgressbarMultiProcessServer object.

Parameters

• progresschar (str) – Character used in the progressbar.

• message (str) – Message writen in the progressbar.

• sleep_time (float) – Time between progressbar updates (in seconds).

• filename (str) – If filename is None (default) then progress will be output to sys.stdout. If it is not None then the progress will be output to a file with name filename. This is usually useful for debugging and testing purposes.

Examples

import multiprocessing
# Create a ProgressbarMultiProcessServer object
pb = ProgressbarMultiProcessServer(message="some message")
# Creates a proxy progressbar for one process passing the value
# corresponding to 100% progress for the first process
proxybar1 = pb.register_client_and_get_proxy_progressbar(60)
# Creates a proxy progressbar for another process
proxybar2 = pb.register_client_and_get_proxy_progressbar(80)
# Create the first process passing the first proxy progressbar as
# an argument
p1 = multiprocessing.Process(target=some_function, args=[proxybar1])
# Creates another process
p2 = multiprocessing.Process(target=some_function, args=[proxybar2])
# Start both processes
p1.start()
p2.start()
# Call the start_updater method of the ProgressbarMultiProcessServer
pb.start_updater()
# Joint the process and then call the stop_updater method of the
# ProgressbarMultiProcessServer
p1.join()
p2.join()
pb.stop_updater()

_update_client_data_list() → None

This method process the communication between the client and the server.

register_client_and_get_proxy_progressbar(total_count: int) → pyphysim.progressbar.progressbar.ProgressbarMultiProcessClient

Register a new “client” for the progressbar and returns a new proxy progressbar that the client can use to update its progress by calling the progress method of this proxy progressbar.

The function whose process is tracked by the ProgressbarMultiProcessServer must must call the progress method of the returned ProgressbarMultiProcessClient object with the current count. This is a little less intrusive regarding the tracked function.

Parameters

total_count (int) – Total count that will be equivalent to 100% for function.

Returns

obj – The proxy progressbar.

Return type

ProgressbarMultiProcessClient

class pyphysim.progressbar.progressbar.ProgressbarText(finalcount: int, progresschar: str = '*', message: str = '', output: Any = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Bases: pyphysim.progressbar.progressbar.ProgressbarTextBase

Class that prints a representation of the current progress as text.

You can set the final count for the progressbar, the character that will be printed to represent progress and a small message indicating what the progress is related to.

In order to use this class, create an object outsize a loop and inside the loop call the progress function with the number corresponding to the progress (between 0 and finalcount). Each time the progress function is called a number of characters will be printed to show the progress. Note that the number of printed characters correspond is equivalent to the progress minus what was already printed.

See also

DummyProgressbar

Examples

>> pb = ProgressbarText(100, ‘o’, “Hello Simulation”) >> pb.start() —————- Hello Simulation —————1

1 2 3 4 5 6 7 8 9 0

—-0—-0—-0—-0—-0—-0—-0—-0—-0—-0 >> pb.progress(20) oooooooooo >> pb.progress(40) oooooooooooooooooooo >> pb.progress(50) ooooooooooooooooooooooooo >> pb.progress(100) oooooooooooooooooooooooooooooooooooooooooooooooooo

_ProgressbarText__get_initialization_bartitle() → str

Get the progressbar title.

The title is the first line of the progressbar initialization message.

The bar title is something like the line below

——————- % Progress ——————1

when there is no message.

Returns

The bar title.

Return type

str

Notes

This method is only a helper method called in the _perform_initialization method.

_ProgressbarText__get_initialization_markers() → Tuple[str, str]

The initialization markers ‘mark’ the current progress in the progressbar that will appear below it.

Returns

A tuple containing the ‘two lines’ with the progress markers. That is, (marker_line1, marker_line2)

Return type

Tuple[str, str]

Notes

This method is only a helper method called in the _perform_initialization method.

_perform_initialization() → None

Perform any initializations for the progressbar.

This method should be implemented in sub-classes if any initialization code should be run.

_update_iteration(count: int) → None

Update the progressbar according with the new count.

Parameters

count (int) – The current count to be represented in the progressbar. The progressbar represents this count as a percent value of self.finalcount

class pyphysim.progressbar.progressbar.ProgressbarText2(finalcount: int, progresschar: str = '*', message: str = '', output: Any = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Bases: pyphysim.progressbar.progressbar.ProgressbarTextBase

Class that prints a representation of the current progress as text.

You can set the final count for the progressbar, the character that will be printed to represent progress and a small message indicating what the progress is related to.

In order to use this class, create an object outsize a loop and inside the loop call the progress function with the number corresponding to the progress (between 0 and finalcount). Each time the progress function is called a number of characters will be printed to show the progress. Note that the number of printed characters correspond is equivalent to the progress minus what was already printed.

Parameters

• finalcount (int) – The total amount that corresponds to 100%. Each time the progress method is called with a number that number is added with the current amount in the progressbar. When the amount becomes equal to finalcount the bar will be 100% complete.

• progresschar (str, optional (default to '*')) – The character used to represent progress.

• message (str, optional) – A message to be shown in the right of the progressbar. If this message contains “{elapsed_time}” it will be replaced by the elapsed time.

• output (File like object) – Object with a ‘write’ method, which controls where the progress-bar will be printed. By default sys.stdout is used, which means that the progress will be printed in the standard output.

_update_iteration(count: int) → None

Update the self.prog_bar member variable according with the new count.

Parameters

count (int) – The current count to be represented in the progressbar. The progressbar represents this count as a percent value of self.finalcount

class pyphysim.progressbar.progressbar.ProgressbarText3(finalcount: int, progresschar: str = '*', message: str = '', output: Any = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Bases: pyphysim.progressbar.progressbar.ProgressbarTextBase

Class that prints a representation of the current progress as text.

You can set the final count for the progressbar, the character that will be printed to represent progress and a small message indicating what the progress is related to.

In order to use this class, create an object outsize a loop and inside the loop call the progress function with the number corresponding to the progress (between 0 and finalcount). Each time the progress function is called a number of characters will be printed to show the progress. Note that the number of printed characters correspond is equivalent to the progress minus what was already printed.

Parameters

finalcountint

The total amount that corresponds to 100%. Each time the progress method is called with a number that number is added with the current amount in the progressbar. When the amount becomes equal to finalcount the bar will be 100% complete.

progresscharstr, optional (default to ‘*’)

The character used to represent progress.

messagestr, optional

A message to be shown in the progressbar.

outputFile like object

Object with a ‘write’ method, which controls where the progress-bar will be printed. By default sys.stdout is used, which means that the progress will be printed in the standard output.

_update_iteration(count: int) → None

Update the self.prog_bar member variable according with the new count.

Parameters

count (int) – The current count to be represented in the progressbar. The progressbar represents this count as a percent value of self.finalcount

class pyphysim.progressbar.progressbar.ProgressbarTextBase(finalcount: int, progresschar: str = '*', message: str = '', output: Any = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Bases: pyphysim.progressbar.progressbar.ProgressBarBase

Base class for Text progressbars.

Parameters

• finalcount (int) – The total amount that corresponds to 100%. Each time the progress method is called with a number that number is added with the current amount in the progressbar. When the amount becomes equal to finalcount the bar will be 100% complete.

• progresschar (str, optional) – The character used to represent progress.

• message (str, optional) – A message to be shown in the top of the progressbar.

• output (File like object) – Object with a ‘write’ method, which controls where the progress-bar will be printed. By default sys.stdout is used, which means that the progress will be printed in the standard output.

Notes

Derived classes must implement at least _update_iteration and this method should update the prog_bar member variable with the text representation of the progress.

_display_current_progress() → None

Refresh the progress representation.

All text progressbars should implement the _update_iteration to update the prog_bar member variable with the text representation of the progressbar.

This method is responsible to sending this text representation to the output.

_get_percentage_representation(percent: float, central_message: str = '{percent}%', left_side: str = '[', right_side: str = ']') → str

Get the percent representation as a string suitable to the text progressbar.

Parameters

• percent (float) – The percentage to be represented.

• central_message (str) – A message that will be in the middle of the percentage bar. If there is the label ‘{percent}’ in the central_message it will be replaced by the percentage. If there is the label ‘{elapsed_time}’ in the central_message it will be replaced by the elapsed time. Note that this message should be very small, since it hides the progresschars.

• left_side (str) – The left side of the bar.

• right_side (str) – The right side of the bar.

Returns

representation – A string with the representation of the percentage.

Return type

str

_maybe_delete_output_file() → None

Delete the output file (if there is any) when delete_progress_file_after_completion is set to True.

_perform_finalizations() → None

Perform any finalization (cleanings) after the progressbar stops.

property width

Get method for the width property.

class pyphysim.progressbar.progressbar.ProgressbarZMQClient(client_id: int, ip: str, port: int, finalcount: int)

Bases: pyphysim.progressbar.progressbar.ProgressbarDistributedClientBase

Proxy progressbar that behaves like a ProgressbarText object, but is actually updating a ProgressbarZMQServer progressbar.

The basic idea is that this proxy progressbar has the “progress” method similar to the standard ProgressbarText class. However, when this method is called it will update a value that will be read by a ProgressbarZMQServer object instead.

Parameters

• client_id (ClientID) – The client ID.

• ip (IPAddress) – A string representing the IP address of the server.

• port (PortNumber) – The port number used by the server.

_perform_initialization() → None

Creates the “push socket”, connects it to the socket of the main progressbar and then updates the progress.

This function will be called only in the first time the “progress” method is called. Subsequent calls to “progress” will actually calls the “_progress” method.

Parameters

count (int) – The new amount of progress.

_update_iteration(count: int) → None

Updates the proxy progress bar.

Parameters

count (int) – The new amount of progress.

class pyphysim.progressbar.progressbar.ProgressbarZMQServer(progresschar: str = '*', message: str = '', sleep_time: float = 1.0, filename: Optional[str] = None, ip: str = 'localhost', port: int = 7396, style: str = 'text2')

Bases: pyphysim.progressbar.progressbar.ProgressbarDistributedServerBase

Distributed “server” progressbar using ZMQ sockets.

In order to track the progress of distributed computations two classes are required, one that acts as a central point and is responsible to actually show the progress (the server), and other class that acts as a proxy (the client) and is responsible to sending the current progress to the server. There will be one object of the “server class” and one or more objects of the “client class”, each one tracking the progress of one of the distributed computations.

This class acts like the server. It creates a ZMQ socket which expects (string) messages in the form “client_id:current_progress”, where the client_id is the ID of one client progressbar previously registered with the register_client_and_get_proxy_progressbar method while the current_progress is a “number” with the current progress of that client.

Note that the client proxybar for this class is implemented in the ProgressbarZMQClient class.

Parameters

• progresschar (str) – Character used in the progressbar.

• message (str) – Message writen in the progressbar.

• sleep_time (float) – Time between progressbar updates (in seconds).

• filename (str) – If filename is None (default) then progress will be output to sys.stdout. If it is not None then the progress will be output to a file with name filename. This is usually useful for debugging and testing purposes.

• ip (IPAddress) – An string representing the address of the server socket. Ex: ‘192.168.0.117’, ‘localhost’, etc.

• port (PortNumber) – The port to bind the socket.

_parse_progress_message(message: str) → None

Parse the message sent from the client proxy progressbars.

The messages sent from the proxy progressbars are in the form ‘client_id:current_count’. We need to set the element of index “client_id” in self._client_data_list to the value of “current_count”. This method will simply parse the message and perform this operation.

Parameters

message (str) – A string in the form ‘client_id:current_count’.

_update_client_data_list() → None

This method process the communication between the client and the server.

This method will read the received messages in the socket which were sent by the clients (ProgressbarZMQClient objects) and update self._client_data_list variable accordingly. The messages are in the form “client_id:current_progress”, which is parsed by the _parse_progress_message method.

Notes

This method is called inside a loop in the _update_progress method.

_update_progress(filename: Optional[str] = None, start_delay: float = 0.0) → None

Collects the progress from each registered proxy progressbar and updates the actual visible progressbar.

Parameters

• filename (str) – Name of a file where the data will be written to. If this is None then all progress will be printed in the standard output (default)

• start_delay (float) – Delay in seconds before starting the progressbar. During this time it is still possible to register new clients and the progressbar will only be shown after this delay.

Notes

We re-implement it here only to create the ZMQ socket. After that we call the base class implementation of _update_progress method. Note that the _update_progress method in the base class calls the _update_client_data_list and we indeed re-implement this method in this class and use the socket created here in that implementation.

property ip

Get method for the ip property.

Returns

The string representing the address of the server socket.

Return type

str

property num_clients

Number of registered clients

property port

Get method for the port property.

Returns

The port used.

Return type

int

register_client_and_get_proxy_progressbar(total_count: int) → pyphysim.progressbar.progressbar.ProgressbarZMQClient

Register a new client progressbar and return a proxy to it.

Parameters

total_count (int) – The total count for the client we are registering.

Returns

The proxy progressbar.

Return type

ProgressbarZMQClient

Module contents