{"id":21954134,"url":"https://github.com/the-lukez/timestringpy","last_synced_at":"2025-10-04T18:57:31.716Z","repository":{"id":240315995,"uuid":"802261989","full_name":"The-LukeZ/TimestringPy","owner":"The-LukeZ","description":"Parse a human readable time string into a floating number of [time-unit].","archived":false,"fork":false,"pushed_at":"2024-07-14T04:08:47.000Z","size":42,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-27T22:48:13.468Z","etag":null,"topics":["converter","string","time","timedelta","timeparser","timestring"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/The-LukeZ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-17T21:06:59.000Z","updated_at":"2024-12-11T06:57:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"abfe93e5-facd-4068-ac3d-715dd4cb7b11","html_url":"https://github.com/The-LukeZ/TimestringPy","commit_stats":null,"previous_names":["the-lukez/timestringpy"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-LukeZ%2FTimestringPy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-LukeZ%2FTimestringPy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-LukeZ%2FTimestringPy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-LukeZ%2FTimestringPy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/The-LukeZ","download_url":"https://codeload.github.com/The-LukeZ/TimestringPy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245001843,"owners_count":20545319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["converter","string","time","timedelta","timeparser","timestring"],"created_at":"2024-11-29T07:16:07.859Z","updated_at":"2025-10-04T18:57:31.689Z","avatar_url":"https://github.com/The-LukeZ.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TimestringPy\n\n\u003e Parse a human readable time string into seconds or a specified return unit.\n\nOrinigal source code: [npm i timestring](https://www.npmjs.com/package/timestring) (Javascript)\n\n## Installation\n\n```bash\npip install TimestringPy\n# or\npip install git+https://github.com/The-LukeZ/TimestringPy\n```\n\n## Usage\n\n### Overview\n\n```py\nimport timestring\n\nvalue = '1h 15m'\ntime = timestring.parse_timestring(value)\n\nprint(time) # will print 4500\n```\n\n**By default the returned time value from `timestring` will be a `float`.**\n\nThe time string can contain as many time groups as needed:\n\n```py\nimport timestring\n\nvalue = '1d 3h 25m 18s'\ntime = timestring.parse_timestring(value)\n\nprint(time) # will print 98718\n```\n\nand can be as messy as you like:\n\n```py\nimport timestring\n\nvalue = '1 d    3HOurS 25              min         1   8s'\ntime = timestring.parse_timestring(value)\n\nprint(time) # will print 98718\n```\n\n### Keywords\n\n`timestring` will parse the following default keywords into time values:\n\n1. `ms, milli, millisecond, milliseconds` - will parse to milliseconds\n2. `s, sec, secs, second, seconds` - will parse to seconds\n3. `m, min, mins, minute, minutes` - will parse to minutes\n4. `h, hr, hrs, hour, hours` - will parse to hours\n5. `d, day, days` - will parse to days\n6. `w, week, weeks` - will parse to weeks\n7. `mon, mth, mths, month, months` - will parse to months\n8. `y, yr, yrs, year, years` - will parse to years\n\nKeywords can be used interchangeably:\n\n```py\nimport timestring\n\nvalue = '1day 15h 20minutes 15s'\ntime = timestring.parse_timestring(value)\n\nprint(time) # will print 141615\n```\n\n### Return Time Value\n\nBy default the return time value will be in seconds. This can be changed by passing one of the strings form the default time-units or an element from the `unit_map`-parameter:\n\n1. `ms` - Milliseconds\n2. `s` - Seconds\n3. `m` - Minutes\n4. `h` - Hours\n5. `d` - Days\n6. `w` - Weeks\n7. `mth` - Months\n8. `y` - Years\n\n```py\nvalue = '22h 16m'\n\nhours = timestring.parse_timestring(value, 'h')\ndays = timestring.parse_timestring(value, 'd')\nweeks = timestring.parse_timestring(value, 'w')\n\nprint(hours) # will print 22.266666666666666\nprint(days) # will print 0.9277777777777778\nprint(weeks) # will print 0.13253968253968254\n```\n\n### Optional Configuration\n\nA few assumptions are made by default:\n\n1. There are 24 hours per day\n2. There are 7 days per week\n3. There are 4 weeks per month\n4. There are 12 months per year\n5. There are 365.25 days per year\n\nThese options can be changed by passing an `dict` to the `opts`-parameter.\n\nThe following options are configurable:\n\n1. `hoursPerDay`\n2. `daysPerWeek`\n3. `weeksPerMonth`\n4. `monthsPerYear`\n5. `daysPerYear`\n\n```py\nimport timestring\n\nvalue = '1d'\nopts = {\n  'hoursPerDay': 1\n}\n\ntime = timestring.parse_timestring(value, 'h', opts=opts) # 'h' because we want the number of hours\n\nprint(time) # will print 1.0\n```\n\nIn the example above `hoursPerDay` is being set to `1`. When the time string is being parsed, the return value is being specified as hours. Normally `1d` would parse to the number of seconds in one day à `24h` (as by default there are 24 hours in a day) but because `hoursPerDay` has been set to `1`, `1d` will now only parse to the number of seconds in `1` hour (aka `1d` here).\n\nThis would be useful for specific application needs.\n\n_Example - Employees of my company work 7.5 hours a day, and only work 5 days a week. In my time tracking app, when they type `1d` i want 7.5 hours to be tracked. When they type `1w` i want 5 days to be tracked etc._\n\n```py\nimport timestring\n\nopts = {\n  'hoursPerDay': 7.5,\n  'daysPerWeek': 5\n}\n\nhoursToday = timestring.parse_timestring('1d', 'h', opts)\ndaysThisWeek = timestring.parse_timestring('1w', 'd', opts)\n\nprint(hoursToday) # will print 7.5\nprint(daysThisWeek) # will print 5.0\n```\n\nYou can also pass your own time units to make more languages available.\n\n### Example\n\n\u003e You have the same example as above, but now you want your German users to type '1 Tag' instead of '1 day' (they may not know the wording), but you want the hours of the day and the amount of days they typed in.\n\n```py\nvalue = '1 tag'\n\nunits = {\n    \"d\": [\"tag\", \"d\", \"day\", \"days\"]\n}\n\nopts = {\n  'hoursPerDay': 7.5,\n  'daysPerWeek': 5\n}\n\nhoursToday = timestring.parse_timestring(value, 'h', opts, units)\ndaysThisWeek = timestring.parse_timestring(value, 'd', opts, units)\n\nprint(hoursToday) # will print 7.5 (7.5 hours)\nprint(daysThisWeek) # will print 1.0 (1 day)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-lukez%2Ftimestringpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthe-lukez%2Ftimestringpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-lukez%2Ftimestringpy/lists"}