From a2758ba4dd70ba3aa18f3ea4fdfb919b22abd2c8 Mon Sep 17 00:00:00 2001 From: Shraddha Kishan Tripathi Date: Fri, 13 Aug 2021 23:52:32 +0530 Subject: [PATCH] Update readme. v2.1 ready --- README.md | 96 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 57 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 4b94c5a..c29cf86 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/randomtimestamp?label=Python) ![PyPI - License](https://img.shields.io/pypi/l/randomtimestamp?label=License&color=red) ![Maintenance](https://img.shields.io/maintenance/yes/2022?label=Maintained) ![PyPI](https://img.shields.io/pypi/v/randomtimestamp?label=PyPi) ![PyPI - Status](https://img.shields.io/pypi/status/randomtimestamp?label=Status) ![PyPI - Format](https://img.shields.io/pypi/format/randomtimestamp?label=Format) ![PyPI - Downloads](https://img.shields.io/pypi/dm/randomtimestamp?label=Downloads&color=yellow) -# randomtimestamp (v2.0.0) +# randomtimestamp (v2.1) Random timestamp generator ## Installation You know it: @@ -13,73 +13,91 @@ randomtimestamp can be used from the command line or imported as a python module #### Command line usage To use the script from command line ``` - $randomtimestamp + $ randomtimestamp 30-08-1995 17:58:14 ``` #### Python Module Usage -In v2.0.0, the function **randomtimestamp** takes six optional arguments: +In v2.1, the functions **randomtimestamp**, **random_time**, and **random_date** are available. + +1. **randomtimestamp()** takes six optional arguments. A call without arguments returns a datetime between **January 1st, 1950, 00:00:00** and **({today}, 23:59:59)**. + **NOTE**: **start/end** are resolved before **start_year/end_year**, therefore **start_year/end_year** have no effect if **start/end** have been provided. + **WARNING [breaking changes]** ⚠️ : Order of arguments to **randomtimestamp** has been changed in v2.1. If you're passing parameters as positionals, be careful before upgrading. The function also returns a *datetime* object rather than a string. ``` randomtimestamp( start_year: int = 1950, - text: bool = True, end_year: int = None, + text: bool = False, start: datetime.datetime = None, end: datetime.datetime = None, pattern: str = "%d-%m-%Y %H:%M:%S" - ) + ) -> Union[datetime, str]: ``` -Order of **start_year** & **text** hasn't been changed in v2.0.0 for backward compatibility. Future versions may not support the same order of arguments. - -*Order of resolution:* -1. start/end -2. start_year/end_year - -This means providing *start_year/end_year* to function call has no effect if *start/end* are also provided. - -The default values of **start_year** and **text** are *1950* and *True* respectively. -The timestamp is generated between *January 1st, 1950, 00:00:00* and *datetime.now()*. - - -## Features: -1. Call without arguments returns a random timestamp as string (**DD-MM-YYYY HH:MM:SS**), where **HH** follows 24-hour format. Setting **text=False** returns a *datetime* object. -2. Lower limit of **start_year = 1950** has been removed. Now 1 <= start_year <= 9999 is allowed. **end_year** has been added to provide upper limit of timestamp beyond current year (within 1-9999). If **end_year** is not given, current year is used as **end_year**. - - **NOTE**: Both are integers and *start_year <= end_year* is required. If *end_year* is provided, *start_year* is required too. - -3. **start** and **end** arguments are datetime objects and can be used for more precise control over timestamp range. **start_year** & **end_year** have no effect if **start** and **end** are given. If **end** is not given, **datetime.now()** is used as **end**. - - **NOTE**: Both are datetime objects and *start < end* is required. If *end* is provided, *start* is required too. +2. **random_time()** takes four optional arguments. A call without arguments returns a time between **between (00:00:00)** and **(23:59:59)**. + +``` +random_time( + start: datetime.time = time.min, + end: datetime.time = time.max, + text: bool = False, + pattern: str = "%H:%M:%S" + ) -> Union[time, str]: +``` +3. **random_date()** takes four optional arguments. A call without arguments returns a date between **(January 1, 1950)** and **today**. + +``` +random_date( + start: datetime.date = date(1950, 1, 1), + end: datetime.date = datetime.today().date(), + text: bool = False, + pattern: str = "%d-%m-%Y" + ) -> Union[date, str]: +``` +In any of these function calls, **start < end** & **start_year < end_year** is mandatory. **pattern** has no effect if **text = False**. -4. **pattern** can be used to generate timestamps in desired format, using valid formats described in [datetime documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes). The default pattern is **"%d-%m-%Y %H:%M:%S"**. +--- - **NOTE**: *pattern* has no effect if **text=False**. +## Changelog: + +##### v2.1 +- Dropped a minor version identifier to account for the small size of module. Only 2 digits to be used hereafter. +- [Breaking change] Order of arguments to randomtimestamp() changed. Code using older versions without keyword arguments breaks. +- [Breaking change] By default **randomtimestamp()** now generates datetime objects. **text = False** by default. +- Introduced **random_time() & random_date()** to generate only time or date if needed. +##### v2.0.0 +- Ability to provide **start/end** as datetime objects to randomtimestamp() for more precise control. +- Lower limit of **start_year = 1950** removed. +- Ability to use custom datetime pattern as described in [datetime documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes). +##### v1.0.0 +- Randomtimestamp released. Timestamps can be generated between 1950 and current_year. +- The timestamp can be generated as a string (by default) or a datetime object. +--- ## Examples: Here are some examples of the possible syntaxes: ``` - >>> from randomtimestamp import randomtimestamp + >>> from randomtimestamp import randomtimestamp, random_date, random_time >>> randomtimestamp() - '02-06-1970 23:34:10' + datetime.datetime(1970, 6, 2, 23, 34, 10) >>> randomtimestamp(start_year=2020, end_year=2021) + datetime.datetime(2021, 1, 10, 5, 6, 19) + + >>> randomtimestamp(start_year=2020, end_year=2021, text=True) '05-09-2021 17:24:28' - >>> randomtimestamp(start_year=2020, end_year=2021, text=False) - datetime.datetime(2021, 1, 10, 5, 6, 19) + >>> random_time() + datetime.time(13, 18, 14) - >>> from datetime import datetime - >>> start = datetime(2020, 5, 10, 0, 0, 0) - >>> end = datetime(2020, 10, 10, 0, 0, 0) - >>> randomtimestamp(start=start, end=end) - '27-09-2020 20:42:55' + >>> random_date() + datetime.date(1990, 6, 13) - >>> randomtimestamp(start=start, end=end, pattern='%d-%h-%Y %I:%M:%S %p') - '03-Aug-2020 08:06:27 PM' + >>> random_time(text=True, pattern='%I:%M:%S %p') + '08:06:27 PM' ``` In any case, if you ever feel stuck, use **help(randomtimestamp)** inside Python's REPL.