Happenings¶

This module contains a parser of NationStates’ Happenings, with the strong intention of being both complete and convenient.

This page describes how happenings are parsed and processed; to subscribe to the happening feeds use the World methods happenings() and new_happenings().

Examples¶

Greet every nation that moves to a new region:

async for happening in \
        aionationstates.world.new_happenings(filters=['move']):
    if type(happening) is aionationstates.happenings.Move:
        region_name = await happening.new_region.name()
        nation_name = await happening.agent.name()
        print(f'Welcome to {region_name}, {nation_name}!')

Detect regional currency adoption:

region_name = 'the pacific'
regional_currency = 'Denarius'

async for happening in aionationstates.world.new_happenings(
        filters=['change'], regions=[region_name]):
    if type(happening) is aionationstates.happenings.SettingsChange:
        if happening.changes.get('currency') == regional_currency:
            nation_name = await happening.agent.name()
            print(f'{nation_name} has adopted {regional_currency}!')

Detect embassies built and closed:

async for happening in \
        aionationstates.world.new_happenings(filters=['embassy']):
    region_names = await asyncio.gather(*[
        region.name() for region in happening.regions])
    if type(happening) is aionationstates.happenings.EmbassyEstablishment:
        print('{} ❤️ {}'.format(*region_names))
    elif type(happening) is aionationstates.happenings.EmbassyCancellation:
        print('{} 💔 {}'.format(*region_names))

Design considerations¶

Parsing happenings can serve a variety of use-cases. You may want to maintain an endorsement graph for your region, which would require very specific handling of a handful of happening types (notably Endorsement, EndorsementWithdrawal, Move, and CTE) or you might be after graphing game activity over time, and thus need to process a broad spectrum of happenings very generically. This module seeks to accomodate both the precise and broad use-cases.

Base classes¶

Starting with the cold hard truth–

class UnrecognizedHappening¶

A happening that wasn’t recognized by the system.

Most likely cause of this is the futility of this measly effort against the inescapable and ever-growing chaos of our Universe.

Not necessarily an error in the parsing system, rather an indicator of its incompleteness.

Note that all the other classes in the happenings module inherit from this class, so all the attributes listed below are present on them as well.

id¶

The happening id.

Type: int

timestamp¶

Time of the happening.

Type: naive UTC datetime.datetime

text¶

The unparsed happening text. May contain HTML tags and character references. You generaly shouldn’t have to use this.

Type: str

Now let’s look at how this module functions when it works as intended, shall we?

On the most basic level, all happenings divide into two groups:

class Action¶

Bases: aionationstates.happenings.UnrecognizedHappening

A direct action taken by a player.

agent¶

The player who took the action.

Type: Nation

class Consequence¶

Bases: aionationstates.happenings.UnrecognizedHappening

A result of previous actions.

The rest of data classes in this module inherit from the classes above.

Additionally, there are generalizable characteristics some happenings share, that can’t be separated well into categories:

class Regional¶

Bases: aionationstates.happenings.UnrecognizedHappening

An event taking place in a single region.

region¶

The region the event took place inside of.

Type: Region

class Affecting¶

Bases: aionationstates.happenings.UnrecognizedHappening

An event passively involving a player.

patient¶

The player who was passively involved in the event.

Type: Nation

Base classes unifying a set of caracteristics like these can be seen throughout the rest of the module.

Categories of happenings¶

Embassies¶

class Embassy¶

Bases: aionationstates.happenings.UnrecognizedHappening

Base class for any event related to an embassy between two regions.

regions¶

Regions sharing an embassy.

Type: a frozenset of two Region

class EmbassyEstablishment¶

Bases: aionationstates.happenings.Consequence, aionationstates.happenings.Embassy

An embassy being established between two regions.

class EmbassyCancellation¶

Bases: aionationstates.happenings.Consequence, aionationstates.happenings.Embassy

Embassy being cancelled between two regions.

class EmbassyOrder¶

Bases: aionationstates.happenings.Action, aionationstates.happenings.RegionalAdministrative, aionationstates.happenings.Embassy

Base class for any action affecting an embassy.

other_region¶

Region the embassy is with.

Type: Region

class EmbassyConstructionRequest¶

Bases: aionationstates.happenings.EmbassyOrder

A nation proposing construction of embassies between two regions.

class EmbassyConstructionConfirmation¶

Bases: aionationstates.happenings.EmbassyOrder

A nation accepting a request to construct embassies between two regions.

class EmbassyConstructionRequestWithdrawal¶

Bases: aionationstates.happenings.EmbassyOrder

A nation withdrawing a request to construct embassies between two regions.

class EmbassyConstructionAbortion¶

Bases: aionationstates.happenings.EmbassyOrder

A nation aborting construction of embassies between two regions.

class EmbassyClosureOrder¶

Bases: aionationstates.happenings.EmbassyOrder

A nation ordering closure of embassies between two regions.

Administration of a region¶

class RegionalAdministrative¶

Bases: aionationstates.happenings.Regional

Base class for any action taken by regional administration, or a change thereof.

class DelegateChange¶

Bases: aionationstates.happenings.Consequence, aionationstates.happenings.RegionalAdministrative

A region changing World Assembly Delegates.

Note that NationStates spreads this out to three distinct happening formats:

delegates changing;
a nation taking the free delegate position; and
a delegate being removed, leaving the position empty.

As I believe this to be superfluous, this class represents all three. In case either the old of new delegate is missing, the corresponding attribute will be set to None.

new_delegate¶

Type: Nation or None

old_delegate¶

Type: Nation or None

class OfficerAppointment¶

Bases: aionationstates.happenings.Action, aionationstates.happenings.Affecting, aionationstates.happenings.RegionalAdministrative

A nation appointing a Regional Officer.

title¶

Title of the new officer.

Type: str

authority¶

Authority of the new officer.

Type: Authority

class OfficerDismissal¶

Bases: aionationstates.happenings.Action, aionationstates.happenings.Affecting, aionationstates.happenings.RegionalAdministrative

A nation dismissing a Regional Officer.

title¶

Title the officer previously held.

Type: str

class DelegateModification¶

Bases: aionationstates.happenings.Action, aionationstates.happenings.RegionalAdministrative

A founder modifying the authority of the World Assembly Delegate.

authority_granted¶

Type: Authority

authority_removed¶

Type: Authority

class OfficerModification¶

Bases: aionationstates.happenings.Action, aionationstates.happenings.Affecting, aionationstates.happenings.RegionalAdministrative

A founder or Delegate modifying one of the Regional Officers.

title¶

Current title of the officer.

Type: str

old_title¶

Title the officer previously held. None if the office wasn’t renamed.

Type: str or None

authority_granted¶

Type: Authority

authority_removed¶

Type: Authority

class PollCreation¶

Bases: aionationstates.happenings.Action, aionationstates.happenings.RegionalAdministrative

A nation creating a new regional poll.

Note that the poll id is inaccessible from the happening, so the created poll can’t be linked directly. The best you can do is request the current poll of the region from the happening.

title¶

Poll title. Don’t rely on this being accurate, some characters (such as brackets) are for whatever horror inducing reason stripped from the happening.