Skip to main content

Epidemiological weeks based on the CDC (MMWR) and ISO week numbering systems.

Project description

A Python package to calculate epidemiological weeks using the CDC (MMWR) and ISO week numbering systems.

Build Status Coverage Status Docs Status Python version support PyPI Package version License


  • Support for both the CDC (MMWR) and ISO week numbering systems.
  • Accurate and tested calculations.
  • Intuitive, clean, and easy-to-use interface.
  • Calculation of the start and end dates of weeks.
  • Iteration of year’s weeks or week’s dates.
  • Rich comparison between weeks.
  • Logical operations for weeks (addition, subtraction and containment).
  • Validation of input data.
  • Works on Python 3.6+ with zero dependencies.
  • Thoroughly tested on all supported Python versions.


$ pip install -U epiweeks

Basic Usage

from epiweeks import Week, Year

week = Week(2019, 1)
# 2019-01-05

for week in Year(2019).iterweeks():
# 2019-01-05
# 2019-01-12
# ...
# 2019-12-21
# 2019-12-28

Online Tool

The following is a simple online tool that was developed to calculate epidemiological weeks (CDC system only) using the latest version of this package:


Please see for full documentation of this package, including overview, more usage examples and API reference.


Contributions are welcome! See CONTRIBUTING.rst for more info.


The main author is Mohammed Alshehri — @dralshehri.


This package is distributed under an MIT license. See LICENSE.

Change Log


  • Improved exception messages by including the type or value used.
  • Improved PyPI packaging by removing unnecessary files.
  • Updated related tests and documentations.


  • Fixed some typos.
  • Improved documentation.


  • Changed the parameter method, which sets how the weeks are numbered, to system for better clarity and intuitive usage.
  • Updated documentation and unit tests.
  • Other minor fixes and enhancements.


  • Dropped support for Python 3.5.
  • Added fromstring() classmethod to allow constructing the Week object from a formatted string, for example ‘2019W08’ or ‘201908’.
  • Added cdcformat() method to return a formatted string like the one used by US CDC for epi weeks, for example for week 8 of 2019 it returns ‘201908’.
  • Added daydate() method to return the date of specific weekday for a week.
  • Changed the optional value ‘WHO’ of the parameter method to ‘ISO’.
  • Changed the fromdate() classmethod of Week object to accept a date object as an argument instead of year, month, and day.
  • Made the Week and Year objects hashable.
  • Improved rich comparison methods.
  • Improved input data validation.
  • Updated and improved documentation examples.
  • Updated unit tests.
  • Other minor fixes and enhancements.


  • First release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for epiweeks, version 2.1.2
Filename, size File type Python version Upload date Hashes
Filename, size epiweeks-2.1.2-py3-none-any.whl (6.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size epiweeks-2.1.2.tar.gz (16.8 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page