reuters-style

A Python library that format dates, numbers and text to conform with the Reuters Style Guide, the standards that guide the world’s largest independent newsroom

Installation

Install the package from the Python Package Index (PyPI) with pipenv:

pipenv install reuters-style

Functions

A collection of functions for formatting date, text and numbers:

reuters_style.date(dt: datetime) → str

Format a date according to Reuters style.

Style guide entry:

In text, use the sequence month/day/year, e.g., “Iraq’s invasion of Kuwait on Aug. 2, 1990, led to…” or “the Aug. 2 invasion” or “the August 1990 invasion.”

If a specific date is used, put the year inside commas. Spell out months in text, but abbreviate them followed by a full stop when they are used with a specific date – Jan.1.

When spelling out duration, write, “The tournament runs from May 22 to 24,” not “…runs from May 22-24.” Write “arrived on Monday,” not “arrived Monday” and “on Tuesday,” rather than “yesterday,” “today,” “tomorrow.” Write “the 1939-45 war” but “from 1939 to 1945,” not “from 1939-45.” Write 9/11, not 9-11. In commodities stories, write “Brazil’s 2013/14 soybean crop” (conventional use), not “2013-14.”

Abbreviate as follows, noting the dot after the abbreviation: Jan., Feb., March, April, May, June, July, Aug., Sept., Oct., Nov., Dec.

Parameters:

dt – The datetime to format. (datetime)

Returns:

The formatted date. (str)

Examples

>>> import reuters_style
>>> reuters_style.date(datetime(2021, 9, 1))
'Sept. 1, 2021'
>>> reuters_style.date(datetime(2021, 3, 1))
'March 1, 2021'
reuters_style.dayofweek(dt: datetime, tabular: bool = False) → str

Format the day of the week according to Reuters style.

Style guide entry:

Always precede the day of the week with the word “on” as in she said on Monday, not she said Monday. Do not abbreviate the days of the week, except in a tabular format: Sun, Mon, Tue, Wed, Thu, Fri, Sat (three letters, without periods).

Parameters:

  • dt – The datetime to format. (datetime)

  • tabular – Whether to format the day of the week for a tabular display. (bool)

Returns:

The formatted day of the week. (str)

Examples

>>> import reuters_style
>>> reuters_style.dayofweek(datetime(2021, 9, 1))
'Wednesday'
>>> reuters_style.dayofweek(datetime(2021, 9, 1), tabular=True)
'Wed'
reuters_style.time(dt: datetime, include_timezone: bool = True) → str

Format a time according to Reuters style.

Style guide entry:

Abbreviations of time zones are acceptable providing the GMT equivalent is given. BST (British Summer Time) = GMT +1 CET (Central European Time) = GMT +1 CDT (Central Daylight Time) = GMT -5 CST (Central Standard Time) = GMT -6 EST (Eastern Standard Time) = GMT -5 MDT (Mountain Daylight Time) = GMT -6 MST (Mountain Standard Time) = GMT -7 PST (Pacific Standard Time) = GMT -8.and

When referring to times, first give the local time by the 12-hour clock (without using the words local time) and follow it with a bracketed conversion to a 24-hour clock time for a specified time zone, e.g., “will meet at 10 a.m. (1600 GMT).”

Use figures except for noon and midnight. Use a colon to separate hours and minutes, e.g., 3:15 p.m. Use the style “on Friday,” “on Saturday,” rather than the looser “today,” “yesterday,” “tomorrow.”

Do not use phrases like “several months ago” or “recently,” which suggest we do not know when something happened or are too lazy to find out. Be precise – “last August” or “on Feb. 2.”

Parameters:

  • dt – The datetime to format. (datetime)

  • include_timezone – Whether to include the timezone in the result. (bool)

Returns:

The formatted time. (str)

Examples

>>> import reuters_style
>>> from datetime import datetime
>>> reuters_style.time(datetime(2021, 9, 1, 12, 0))
'noon GMT'
>>> reuters_style.time(datetime(2021, 9, 1, 12, 0), include_timezone=False)
'noon'
>>> reuters_style.time(datetime(2021, 9, 1, 12, 30))
'12:30 p.m. GMT'
>>> reuters_style.time(datetime(2021, 9, 1, 12, 30), include_timezone=False)
'12:30 p.m.'
>>> import pytz
>>> tz = pytz.timezone('Africa/Johannesburg')
>>> dt = tz.localize(datetime(2021, 9, 1, 12, 30))
>>> reuters_style.time(dt)
'12:30 p.m. SAST'
>>> reuters_style.time(dt, include_timezone=False)
'12:30 p.m. (1030 GMT)'
reuters_style.validate_slug(slug: str) → bool

Check whether a full slug is valid.

Style guide entry:

A slug is a simple human readable method of grouping content for packaging, either internally or externally. By using the same slug for the same real world event Reuters can ensure that it is easy to find pictures, text, graphics, video, audio that all belong together.

A slug has two parts:

  • a packaging slug (FERRARI-IPO/)

  • a wild slug (PROSPECTUS)

They come together as the full slug in FERRARI-IPO/PROSPECTUS.

Parameters:

slug – The full slug to validate. (str)

Returns:

Whether the full slug is valid. (bool)

Raises:

ValueError – If the full slug is invalid.

Examples

>>> import reuters_style
>>> reuters_style.validate_slug('FERRARI-IPO/PROSPECTUS')
True
>>> reuters_style.validate_slug('FERRARI-IPO/PROSPECTUS REPORT')
Traceback (most recent call last):
    ...
ValueError: Wild slug can only contain uppercase letters, hyphens and slashes.
reuters_style.validate_packaging_slug(slug: str) → bool

Check whether a packaging slug is valid.

Style guide entry:

A slug is a simple human readable method of grouping content for packaging, either internally or externally. By using the same slug for the same real world event Reuters can ensure that it is easy to find pictures, text, graphics, video, audio that all belong together.

A slug has two parts:

  • a packaging slug (FERRARI-IPO/)

  • a wild slug (PROSPECTUS)

They come together as the full slug in FERRARI-IPO/PROSPECTUS.

The packaging slug is the part that is used to pull a package of stories together with visuals and so MUST STAY THE SAME for as long as the story runs through updates, wrap-ups and for days, weeks or even months sometimes. Once a packaging slug (the first two words before the “/” mark) has been established, it should be adopted by all services and regions. For example: MALAYSIA-POLITICS/ or BRITAIN-POLITICS/.

Parameters:

slug – The packaging slug to validate. (str)

Returns:

Whether the packaging slug is valid. (bool)

Raises:

ValueError – If the packaging slug is invalid.

Examples

>>> import reuters_style
>>> reuters_style.validate_packaging_slug('FERRARI-IPO/')
True
>>> reuters_style.validate_packaging_slug('FERRaRI IPO')
Traceback (most recent call last):
    ...
ValueError: Packaging slug can only contain uppercase letters, hyphens and slashes.
reuters_style.validate_wild_slug(slug: str) → bool

Check whether a wild slug is valid.

Style guide entry:

A slug is a simple human readable method of grouping content for packaging, either internally or externally. By using the same slug for the same real world event Reuters can ensure that it is easy to find pictures, text, graphics, video, audio that all belong together.

A slug has two parts:

  • a packaging slug (FERRARI-IPO/)

  • a wild slug (PROSPECTUS)

They come together as the full slug in FERRARI-IPO/PROSPECTUS.

If this story develops other angles that warrant separate content, you can add words after the “/” mark, like this: MALAYSIA-POLITICS/STATEMENT, MALAYSIA-POLITICS/PROTEST, or BRITAIN-POLITICS/PM. The part after the “/” mark is called the wild slug.

Parameters:

slug – The wild slug to validate. (str)

Returns:

Whether the wild slug is valid. (bool)

Raises:

ValueError – If the wild slug is invalid.

Examples

>>> import reuters_style
>>> reuters_style.validate_wild_slug('PROSPECTUS')
True
>>> reuters_style.validate_wild_slug('PROSPECTUS REPORT')
Traceback (most recent call last):
    ...
ValueError: Wild slug can only contain uppercase letters, hyphens and slashes.

Objects

A set of dataclasses for formatting Reuters-specific objects:

class reuters_style.RIC(code: str, title: str)

Bases: object

Metadata about a Refinitiv Instrument Code.

Refinitiv Instrument Codes (RICs), or ticker symbols, are crucial in helping customers find news and market data. All financial instruments — stocks, bonds, currencies and commodities — as well as many types of economic data have RICs.

Real world codes include IBM.N, EUR=, and XAU=.

Parameters:

  • code – The Refinitiv Instrument Code. (str)

  • title – The more verbose definition of the code. (str)

Examples

>>> import reuters_style
>>> reuters_style.RIC(code='AAPL.O', title='Apple Inc')
RIC(code='AAPL.O', title='Apple Inc')
>>> obj = reuters_style.RIC(code='XAU=', title='Gold')
>>> obj.code
'XAU='
>>> obj.title
'Gold'
>>> print(obj)
XAU=
code: str

The Refinitiv Instrument Code

title: str

The more verbose definition of the code

__init__(code: str, title: str) → None
class reuters_style.Slug(packaging_slug: str, wild_slug: str)

Bases: object

A full Reuters slug.

Style guide entry:

A slug is a simple human readable method of grouping content for packaging, either internally or externally. By using the same slug for the same real world event Reuters can ensure that it is easy to find pictures, text, graphics, video, audio that all belong together.

A slug has two parts:

  • a packaging slug (FERRARI-IPO/)

  • a wild slug (PROSPECTUS)

They come together as the full slug in FERRARI-IPO/PROSPECTUS.

Parameters:

  • packaging_slug – The packaging slug. (str)

  • wild_slug – The wild slug. (str)

Examples

>>> import reuters_style
>>> reuters_style.Slug(packaging_slug='FERRARI-IPO/', wild_slug='PROSPECTUS')
Slug(packaging_slug='FERRARI-IPO/', wild_slug='PROSPECTUS')
>>> obj = reuters_style.Slug(packaging_slug='FERRARI-IPO/', wild_slug='PROSPECTUS')
>>> obj.packaging_slug
'FERRARI-IPO/'
>>> obj.wild_slug
'PROSPECTUS'
>>> print(obj)
FERRARI-IPO/PROSPECTUS
>>> obj.full_slug
'FERRARI-IPO/PROSPECTUS'
>>> obj.validate()
True
packaging_slug: str

The packaging slug

wild_slug: str

The wild slug

property full_slug: str

The full slug.

Returns:

The full slug. (str)

validate() → bool

Validate the slug.

Returns:

Whether the slug is valid. (bool)

Raises:

ValueError – If the slug is invalid.

__init__(packaging_slug: str, wild_slug: str) → None