Documentation — cookies_utilities 0.0.1 documentation

# Documentation

## Functions

### cookies_utilities.copy_datetime

cookies_utilities.copy_datetime(dt, options={})

  Create a copy of a datetime.datetime object.

  Parameters:

    - dt (datetime.datetime) – The original object.

    - options (dict) – If you wish to overwrite certain fields, please specify them using this dictionary (optional). The keys must be in [‘year’, ‘month’, ‘day’, ‘hour’, ‘minute’, ‘second’, ‘microsecond’, ‘tzinfo’, ‘fold’].

  Return type:

    datetime.datetime

Example

    import cookies_utilities as cu
    import datetime

    dt = datetime.datetime.strptime('2016-07-01 02:15:00', '%Y-%m-%d %H:%M:%S')
    dt_copy = cu.copy_datetime(dt, {'minute': 0})  # --> 2016-07-01 02:00:00

### cookies_utilities.get_dates

cookies_utilities.get_dates(start='2016-07-01 02:00:00', end='2016-07-02 01:00:00', format='%Y-%m-%d %H:%M:%S', delta={'days': 0, 'hours': 1, 'minutes': 0, 'weeks': 0}, geniter=False, cast_str=True, format_out=None)

  Returns a list of times from the ‘start’ time to the ‘end’ time, incremented by ‘delta’. Please ensure ‘delta’ is greater than or equal to 1 microsecond.

  If you’re using the result as an iterator, it is recommended to set geniter=True.

  Parameters:

    - start (string) – Start time string.

    - end (string) – End time string (inclusive).

    - format (string) – Conversion format for datetime.strptime.

    - delta (dict) – Timedelta as args for datetime.timedelta (>= 1 microsecond).

    - geniter (bool) – Whether to return as a generator iterator (default False).

    - cast_str (bool) – Whether to convert output to string (default True).

    - format_out (string) – Conversion format for output (default same to format).

  Return type:

    list (or generator iterator) of string (or datetime.datetime)

Example

An example of incrementing by one day.

    import cookies_utilities as cu
    dates = cu.get_dates(
        start='2016/07/01', end='2016/07/03', format='%Y/%m/%d',
        delta={'days': 1}, format_out='%Y-%m-%d')
    print(dates)

    ['2016-07-01', '2016-07-02', '2016-07-03']

An example of incrementing by 20 minutes.

    import cookies_utilities as cu
    dates = cu.get_dates(
        start='2016-07-01 02:00:00', end='2016-07-01 03:00:00',
        format='%Y-%m-%d %H:%M:%S',
        delta={'minutes': 20})
    print(dates)

    ['2016-07-01 02:00:00', '2016-07-01 02:20:00', '2016-07-01 02:40:00', '2016-07-01 03:00:00']

An example of retrieving as a generator iterator.

    import cookies_utilities as cu
    dates = cu.get_dates(
        start='2016/07/01', end='2016/07/03', format='%Y/%m/%d',
        delta={'days': 1}, geniter=True)
    print(type(dates))
    for date in dates:
        print(date)

    <class 'generator'>
    2016/07/01
    2016/07/02
    2016/07/03

### cookies_utilities.convert_time_to_feature

cookies_utilities.convert_time_to_feature(dt, format='%Y-%m-%d %H:%M:%S', period='day', ceiling=None)

  Convert a time to a feature value between 0 and 1. The return feature value represents how much of a period has passed.

  For example, if the period is 1 day, a feature value of noon is 0.5.

  Note 1: When setting the period to a month, the cycle is considered as 31 days regardless of the actual number of days in that month. This is to ensure that the feature value for ‘the 5th day of any month’ is consistent.

  Note 2: When setting the period to a year, the cycle is considered as 366 days regardless of the actual number of days in that year. This is done to ensure that the feature value for ‘the 5th day of any year’ remains the same, regardless of the specific year.

  Parameters:

    - dt (string) – A time string.

    - format (string) – Conversion format for datetime.strptime. If you set this argument to None, we expect ‘dt’ to originally be datetime.datetime object.

    - period (string) – A time period to convert a time to a feature value. This must be in [‘year’, ‘month’, ‘week’, ‘day’, ‘hour’, ‘minute’, ‘second’].

    - ceiling (string) – If you want to round the time when calculating the feature value, specify the rounding granularity in this argument (optional). This must be in [‘year’, ‘month’, ‘day’, ‘hour’, ‘minute’, ‘second’].

  Return type:

    float

    import cookies_utilities as cu

    feature_value = cu.convert_time_to_feature(
        dt='2023-01-02 03:40:50', format='%Y-%m-%d %H:%M:%S',
        period='day', ceiling='hour')
    #  --> 0.125  ( 3:00 am is 12.5% of the day )

    feature_value = cu.convert_time_to_feature(
        dt='2023-01-02 03:40:50', format='%Y-%m-%d %H:%M:%S',
        period='year', ceiling='day')
    #  --> 0.002732  ( 1.0 / 366.0 )

    feature_value = cu.convert_time_to_feature(
        dt='2023-01-02 03:40:50', format='%Y-%m-%d %H:%M:%S',
        period='month', ceiling='day')
    #  --> 0.032258  ( 1.0 / 31.0 )

    feature_value = cu.convert_time_to_feature(
        dt='2023-01-02 03:40:50', format='%Y-%m-%d %H:%M:%S',
        period='week', ceiling='hour')
    #  --> 0.017857  ( 0.125 / 7.0 )

    feature_value = cu.convert_time_to_feature(
        dt='2023-01-02 03:40:50', format='%Y-%m-%d %H:%M:%S',
        period='hour', ceiling='minute')
    #  --> 0.666667  ( 40.0 / 60.0 )

    feature_value = cu.convert_time_to_feature(
        dt='2023-01-02 03:40:50', format='%Y-%m-%d %H:%M:%S',
        period='minute')
    #  --> 0.833333  ( 50.0 / 60.0 )

### cookies_utilities.has_diff_local_and_remote

cookies_utilities.has_diff_local_and_remote(local_dir, remote_url, username=None, password=None, exts='html|css|js', binary_exts='png|jpg|pdf')

  Recursively checks whether the local directory is synchronized with the specified URL.

  For binary files, only their presence and file size will be checked without verifying the content differences.

  Parameters:

    - local_dir (str) – The path to the local directory.

    - remote_url (str) – The URL to be checked against.

    - username (str | None) – The username for basic authentication. If the URL is protected, please specify (optional).

    - password (str | None) – The password for basic authentication. If the URL is protected, please specify (optional).

    - exts (str) – A pipe-separated list of file extensions to be checked. Default is “html|css|js” (optional).

    - binary_exts (str) – A pipe-separated list of binary file extensions to be checked. Default is “png|jpg|pdf” (optional).

  Return type:

    None

Example

An example script of check whether the local directory is synchronized with the specified URL.

    import cookies_utilities as cu
    import getpass

    if __name__ == '__main__':
        username = getpass.getpass('Please enter username: ')
        password = getpass.getpass('Please enter password: ')
        while True:
            cu.has_diff_local_and_remote(
                local_dir='./hoge/',
                remote_url='https://hoge/',
                username=username, password=password,
                exts='html|css|js|tex|sty',
                binary_exts='png|jpg|pdf|pptx|ps|eps',
            )
            print('----- END -----')
            user_input = input('Press Enter to continue or type `q` to quit: ')
            if user_input == 'q':
                break

## Classes

### cookies_utilities.Stopwatch

class cookies_utilities.Stopwatch

  Stopwatch for measuring processing time.

  press(key='')

    Press the stopwatch.

    Parameters:

      key (string) – The idenficator for the time (optional).

  show()

    Show lap times.

Example

    import cookies_utilities as cu
    sw = cu.Stopwatch()
    sw.press('train start')
    # train
    sw.press('train end')
    # test
    sw.press('test end')
    sw.show()

    time1 (train start - train end): 2.000s
    time2 (train end - test end): 1.000s
    total: 3.000s

### cookies_utilities.HtmlHelper

class cookies_utilities.HtmlHelper(title=None)

  Class to help with creating an HTML file.

  Parameters:

    title (str | None) – The title of the HTML (optional).

  append(s)
    Parameters:

      s (str) – String to be appended to the HTML body.

    Return type:

      None

  append_heading(level, s)
    Parameters:

      - level (int) – Integer indicating the heading level.

      - s (str) – Heading String.

    Return type:

      None

  append_markdown(md_path, converter)

    Reads the markdown file, converts it to HTML, and appends to the body.

    Parameters:

      - md_path (str) – Path to the markdown file.

      - converter (Callable[[str], str]) – Function used to convert markdown to HTML.

    Return type:

      None

  to_html(out_path)
    Parameters:

      out_path (str) – Output path for the HTML file.

    Return type:

      None

Example

Below is an example of converting a Markdown file to an HTML file. The mistletoe package is used for the Markdown conversion.

    from cookies_utilities import HtmlHelper
    import mistletoe
    import re

    def main(md_path):
        hh = HtmlHelper()

        # Reads the markdown file, converts it to HTML, and appends to the body.
        assert re.search(r'\.md$', md_path)
        hh.set_markdown(md_path, mistletoe.markdown)

        # You can also customize the CSS.
        # Since `css` attribute is a subclass of a dictionary,
        # you can set it directly by specifying a key.
        #  Ex. hh.css['body']['background'] = 'lemonchiffon'
        # Using the method below, it checks for the existence of
        # the 'body' key and adds it if not present.
        hh.css.set('body', 'background', 'lemonchiffon')

        hh.to_html(re.sub(r'\.md$', '.html', md_path))

    if __name__ == '__main__':
        main('./README.md')

Below is an example of outputting a Pandas DataFrame to an HTML file.

    from cookies_utilities import HtmlHelper
    import pandas as pd

    df = pd.DataFrame(columns=['id', 'name'])
    df.loc[0] = ['001', 'Alice']
    df.loc[1] = ['002', 'Bob']
    df.loc[2] = ['003', 'Carol']

    hh = HtmlHelper()
    hh.append_heading(1, 'Employees')
    hh.append(df.to_html(index=False))
    hh.to_html('employees.html')