Formatting module

pycof.format.GetEmails(nb_email=1, email_address='', port=993, credentials={})[source]

Get latest emails from your address.

Parameters

nb_email (int, optional) – Number of emails to retreive, defaults to 1.
email_address (str, optional) – Email address to use, defaults to ‘’ and uses EMAIL_USER from config file.
port (int, optional) – Port for IMAP, defaults to 993 for Gmail.
credentials (dict, optional) – Credentials to use. See Setup, defaults to {}.

Configuration

The function requires the below arguments in the configuration file.

EMAIL_USER: Email address from which we want to retreive emails. Similar argument as pycof.format.send_email().
EMAIL_PASSWORD: Password for authentication. Similar argument as pycof.format.send_email().
EMAIL_IMAP: IMAP host for connection. Default is imap.gmail.com for Google.

{
"EMAIL_USER": "",
"EMAIL_PASSWORD": "",
"EMAIL_IMAP": "imap.gmail.com"
}

Example

>>> pycof.GetEmails(2)
... +----------------------------+-----------------+----------------+----------------+
... |                       Date |            From |        Subject |             To |
... +----------------------------+-----------------+----------------+----------------+
... |  2021-01-01 04:00:03+01:00 | test@domain.com |          Testo |  me@domain.com |
... |  2021-01-01 03:14:09+01:00 | test@domain.com |   Another test |  me@domain.com |
... +----------------------------+-----------------+----------------+----------------+

Returns

Data frame with last emails.

Return type

pandas.DataFrame

class pycof.format.GoogleCalendar(timezone='Europe/Paris', scopes=['https://mail.google.com/', 'https://www.googleapis.com/auth/calendar.readonly'], token_path=None)[source]

Bases: object

Get all available events on a Google Calendar. The Google credentials file needs to be saved as /etc/.pycof/google.json.

Parameters

timezone (str, optional) – Time zone to transform dates, defaults to ‘Europe/Paris’.
scopes (list, optional) – Targeted permissions required. Check https://developers.google.com/calendar/auth for more details, defaults to [’https://www.googleapis.com/auth/calendar.readonly’].
token_path (str, optional) – Path to the saved token.pickle authentication file, defaults to None and saves in the PYCOF temporary data folder.

Configuration

The function requires a configuration file stored at /etc/.pycof/google.json. This file can be generated at https://developers.google.com/calendar/quickstart/python. User will need to enable the Google Calendar API on the account from Step 1.

get_calendars()[source]

Get list of all available calendars.

Returns: List of all available calendars.
Return type: list

next_events(calendar='primary', maxResults=None, endTime=None, singleEvents=True, orderBy='startTime', *args)[source]

Retreive next events. See https://developers.google.com/calendar/v3/reference/events/list for details for arguments.

Parameters

calendar (str, optional) – ID of the targeted calendar. Use the function get_calendars() to find more calendars, defaults to ‘primary’.
maxResults (int, optional) – Number of future events to retreive, defaults to None.
endTime (datetime.datetime, optional) – Maximum date for the future events, defaults to None
singleEvents (bool, optional) – Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves, defaults to True.
orderBy (str, optional) – The order of the events returned in the result, defaults to ‘startTime’.

Returns

Data Frame with future events.

Return type

pandas.DataFrame

today_events(calendar='primary', singleEvents=True, orderBy='startTime', *args)[source]

Retreive all events for current date. See https://developers.google.com/calendar/v3/reference/events/list for details for arguments.

Parameters

calendar (str, optional) – ID of the targeted calendar. Use the function get_calendars() to find more calendars, defaults to ‘primary’.
singleEvents (bool, optional) – Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves, defaults to True.
orderBy (str, optional) – The order of the events returned in the result, defaults to ‘startTime’.

Returns

Data Frame with all events for today.

Return type

pandas.DataFrame

pycof.format.add_zero(nb)[source]

Converts a number to a string and adds a ‘0’ if less than 10.

Parameters

nb (float): Number to be converted to a string.

Example

>>> pycof.add_zero(2)
... '02'

Returns

str: Converted number qs a string.

pycof.format.display_name(display='first')[source]

Displays current user name (either first/last or full name)

Parameters

display (str): What name to display ‘first’, ‘last’ or ‘full’ (defaults ‘first’).

Example

>>> pycof.display_name()
... 'Florian'

Returns

str: Name to be displayed.

class pycof.format.google_email(credentials={}, scopes=['https://mail.google.com/', 'https://www.googleapis.com/auth/calendar.readonly'], token_path=None)[source]

Bases: object

Simplified class to send email from a Gmail email address with secured connection with developper API. The Google credentials file needs to be saved as /etc/.pycof/google.json.

Parameters

credentials (dict, optional) – Credentials to use which includes the from email address to display. See Setup, defaults to {}.
scopes (list, optional) – Targeted permissions required. Check https://developers.google.com/calendar/auth for more details, defaults to [’https://mail.google.com/’, ‘https://www.googleapis.com/auth/calendar.readonly’].
token_path (str, optional) – Path to the saved token.pickle authentication file, defaults to None and saves in the PYCOF temporary data folder.

Configuration

The function requires a configuration file stored at /etc/.pycof/google.json. This file can be generated at https://developers.google.com/calendar/quickstart/python. User will need to enable the Google Calendar API on the account from Step 1.

Example

>>> _body = '<html><body><h1>This email is a test</h1><p>Hello world!</p></body></html>'
>>> pc.google_email().send(to='email@example.com', subject='Test', body=_body, cc='friend@example.com')
>>> # Alternative where we specify token_path
>>> pc.google_email(token_path='/home/ubuntu/token.pickle').send(to='email@example.com', subject='Test', body=_body, cc='friend@example.com')

getEmails(nb_email=1, include_spam=False, _to='me', *args)[source]

Get latest emails from your Gmail address.

Parameters

nb_email (int, optional) – Number of emails to retreive, defaults to 1.
_to (str, optional) – User ID to use to retreive emails, defaults to ‘me’.

Example

>>> pycof.google_emails().GetEmails(2)
... +----------------------------+-----------------+----------------+---------------+
... |                       Date |            From |        Subject |            To |
... +----------------------------+-----------------+----------------+---------------+
... |  2021-01-01 04:00:03+01:00 | test@domain.com |          Testo |  me@gmail.com |
... |  2021-01-01 03:14:09+01:00 | test@domain.com |   Another test |  me@gmail.com |
... +----------------------------+-----------------+----------------+---------------+

Returns

Data frame with last emails.

Return type

pandas.DataFrame

send(to, subject, body, cc='', return_status=False)[source]

Send the email.

Parameters

to (str) – Recipient of the email.
subject (str) – Subject of the email.
body (str) – Content of the email to be send.
cc (str, optional) – Email address to be copied, defaults to ‘’.
return_status (bool, optional) – Returns status of the email sent, defaults to False.

Returns

If return_status=True, returns a dictionnary with the status of the email.

Return type

dict

pycof.format.group(nb, digits=0, unit='')[source]

Transforms a number into a string with a thousand separator.

Parameters

nb (float): Number to be transformed.
digits (int): Number of digits to round.
unit (str): Unit to be displayed (defaults to ‘’).

Example

>>> pycof.group(12345)
... '12,345'
>>> pycof.group(12345.54321, digits=3)
... '12,345.543'
>>> pycof.group(12.54, digits=3, unit='%')
... '12.54%'

Returns

str: Transformed number.

pycof.format.replace_zero(nb, digits=0)[source]

For a given number, will transform 0 by ‘-’ for display puspose.

Parameters

nb (float): Number to be transformed.

Example

>>> pycof.replace_zero(0)
... '-'
>>> pycof.replace_zero(12345)
... '12'
>>> pycof.replace_zero(12345, digits=1)
... '12,3'

Returns

str: Transformed number as a string.

pycof.format.send_email(to, subject, body, cc='', credentials={}, connection='auto')[source]

Simplified function to send emails. Will look at the credentials at /etc/.pycof/config.json. User can also pass a dictionnary for credentials.

Parameters

to (str): Recipient of the email.
subject (str): Subject of the email.
body (str): Content of the email to be send.
cc (str): Email address to be copied (defaults None).
credentials (dict): Credentials to use to connect to the database. You can also provide the credentials path or the json file name from /etc/.pycof/ (defaults {}).

Configuration

The function requires the below arguments in the configuration file.

EMAIL_USER: Email address from which we want to send the email.
EMAIL_SENDER: Name to display for the sender.
EMAIL_PASSWORD: Password for authentication.
EMAIL_SMTP: SMTP host for connection. Default is smtp.gmail.com for Google.
EMAIL_PORT: Port for authentication.

{
"EMAIL_USER": "",
"EMAIL_SENDER": "",
"EMAIL_PASSWORD": "",
"EMAIL_SMTP": "smtp.gmail.com",
"EMAIL_PORT": "587"
}

Example

>>> content = "This is a test"
>>> pycof.send_email(to="test@domain.com", body=content, subject="Hello world!")

pycof.format.str2bool(value)[source]

Convert a string into boolean.

Parameters

value (str): Value to be converted to boolean.

Example

>>> pycof.str2bool('true')
... True
>>> pycof.str2bool(1)
... True
>>> pycof.str2bool(0)
... False

Returns

bool: Returns either True or False.

pycof.format.week_sunday(date=None, return_week_nb=False)[source]

For a given date, will return the date from previous sunday or week number.

Parameters

date (datetime.date): Date from which we extract the week number/sunday date (defaults to today).
return_week_nb (bool): If True will return week number with sunday basis (defaults False).

Example

>>> pycof.week_sunday(datetime.date(2020, 4, 15))
... datetime.date(2020, 4, 12)
>>> pycof.week_sunday(datetime.date(2020, 4, 15), return_week_nb = True)
... 16

Returns

int: Week number (from 1 to 52) if return_week_nb else date format.

class pycof.misc.EmailSSHTunnel(config, connection='direct', engine='default')[source]: Bases: object

pycof.misc.file_age(file_path, format='seconds')[source]

Computes the age of a file.

Parameters

file_path (str): Path of the file to compute the age.
format (str): Unit in which to compute the age (defaults ‘seconds’). Can either be ‘seconds’, ‘minutes’, ‘hours’ or ‘days’.

Example

>>> pycof.file_age('/home/ubuntu/.bashrc')
... 9937522.32319
>>> pycof.file_age('/home/ubuntu/.bashrc', format='days')
... 11.01812981440972

Returns

int: Age of the file.

pycof.misc.verbose_display(element, verbose=True, sep=' ', end='\n', return_list=False)[source]

Extended print function with tqdm display for loops. Also has argument verbose for automated scripts with overall verbisity argument.

Parameters

element (str): The element to be displayed. Can either be str, range, list.
verbose (bool): Display the element or not (defaults True).
sep (str): The deperator to use of displaying different lists/strings (defaults ‘ ‘).
end (str): How to end the display (defaults ‘n’).
return_list (bool): If it is a list, can return in for paragraph format (defaults False).

Example

>>> for i in pycof.verbose_display(range(15)):
>>>     i += 1
... 100%|#######################################| 15/15 [00:00<00:00, 211122.68it/s]

Returns

str: The element to be displayed.

pycof.misc.write(file, path, perm='a', verbose=False, end_row='\n', credentials={}, profile_name=None, **kwargs)[source]

Write a line of text into a file (usually .txt) or saves data objects. As opposed to Pandas’ built-in functions (to_csv or to_parquet), this function allows to pass AWS IAM credentials similar to pycof.sql.remote_execute_sql().

Parameters

file (str or pandas.DataFrame): Line of text or object to be inserted in the file.
path (str): File on which to write (/path/to/file.txt). Can be any format, not necessarily txt.
perm (str): Permission to use when opening file (usually ‘a’ for appending text, or ‘w’ to (re)write file).
verbose (bool): Return the length of the inserted text if set to True (defaults False).
end_row (str): Character to end the row (defaults ‘n’).
credentials (dict): Credentials to use to connect to AWS S3. You can also provide the credentials path or the json file name from ‘/etc/’ (defaults {}).
profile_name (str): Profile name of the AWS profile configured with the command aws configure (defaults None).
**kwargs (str): Arguments to be passed to pandas function (either to_csv or to_parquet).

Example

>>> pycof.write('This is a test', path='~/pycof_test_write.txt', perm='w')
>>> pycof.write(df, path='s3://bucket/path/to/file.parquet', credentials='config.json')

Returns

int: Number of characters inserted if verbose is True.