Reference¶

Ratelimiting¶

Ratelimiting is handled automatically, with no (clean) way to override the ratelimiter’s behavior. The latter part may change in later versions.

Combining Shards¶

As you are probably aware, NationStates provides a way to request multiple shards for the (ratelimit) cost of one. That is quite a useful feature, and this class has been designed specifically to take full advantage of it.

class ApiQuery¶

A request to the NationStates API.

Although you, as a user, will never need to interact with this class “directly,” it is quite a bit more than an implementation detail.

It it here to provide a way to combine multiple API shards into a single HTTP request.

To achieve that, it overloads the + operator. By “adding” ApiQueries together, you get an ApiQuery which, when awaited, will return a tuple of what the original ApiQueries would have returned by themselves. Let me illustrate.

This code:

name = await nation.name()
population = await nation.population()
wa = await nation.wa()

is functionally equivalent to this:

name, population, wa = await (
    nation.name() + nation.population() + nation.wa())

with the tiny difference that the latter sample sends but a single HTTP request to the API, as opposed to the former, which bombards the poor server hamsters with all three.

As you may have already realized at this point, combining shards into a single request this way is preferable, and you should do that in your code wherever possible.

Note

Standard NS rules for combining shards still apply. Code such as this is not going to work:

nation.name() + region.name()
# ValueError: ApiQueries do not share the same session

nation.census() + nation.censushistory()
# ValueError: ApiQueries contain conflicting params

That’s all well and good, but how do I actually request the shards I need?¶

Nation shards¶

class Nation(name)¶

A class to interact with the NationStates Nation public API.

Shards absent (incomplete):

lastactivity - There is no timestamp version, and the value is kind of useless anyways.
govtpriority - Use the govt() shard.
factbooks, dispatches, factbooklist - Use the dispatchlist() shard.
income, poorest, richest - Use census() scales 72, 73, and 74 respectively. The gdp() shard has been kept, as it appears to be slightly different from scale 76.

id¶

The defining characteristic of a nation, its normalized name. No two nations share the same id, and no one id is shared by multiple nations.

Type: str

url¶

URL of the nation.

Type: str

name()¶

Name of the nation, for example ‘Testlandia’.

Returns: an ApiQuery of str

type()¶

Type of the nation, for example ‘Hive Mind’.

Returns: an ApiQuery of str

fullname()¶

Full name of the nation, for example ‘The Hive Mind of Testlandia’.

Returns: an ApiQuery of str

motto()¶

Motto of the nation.

Returns: an ApiQuery of str

category()¶

Nation’s World Assembly Category.

Returns: an ApiQuery of str

region()¶

Region in which the nation resides.

Returns: an ApiQuery of Region

animal()¶

Nation’s national animal.

Returns: an ApiQuery of str

currency()¶

Nation’s national currency.

Returns: an ApiQuery of str

demonym()¶

Nation’s demonym, as an adjective.

Example: Testlandish, as in ‘I’m proud to be Testlandish.’

Returns: an ApiQuery of str

demonym2()¶

Nation’s demonym, as a noun.

Example: Testlandian, as in ‘I’m a proud Testlandian.’

Returns: an ApiQuery of str

demonym2plural()¶

Plural of the nation’s noun demonym.

Example: Testlandians, as in ‘Here come the Testlandians!’

Returns: an ApiQuery of str

flag()¶

URL of the nation’s flag.

Returns: an ApiQuery of str

majorindustry()¶

The industry prioritized by the nation.

Returns: an ApiQuery of str

influence()¶

An adjective describing nation’s regional influence.

Returns: an ApiQuery of str

leader()¶

Nation’s leader. Either set by the user or the default ‘Leader’.

Returns: an ApiQuery of str

capital()¶

Nation’s capital. Either set by the user or the default ‘name City.’

Returns: an ApiQuery of str

religion()¶

Nation’s main religion. Either set by the user or the default ‘a major religion.’

Returns: an ApiQuery of str

admirable()¶

One of the nation’s qualities, at random.

Example: ‘environmentally stunning’

Returns: an ApiQuery of str

animaltrait()¶

Short characteristic of the nation’s national animal.

Example: ‘frolics freely in the nation’s sparkling oceans’

Returns: an ApiQuery of str

crime()¶

A sentence describing the nation’s crime levels.

Example: ‘Crime is totally unknown, thanks to a very well-funded police force and progressive social policies in education and welfare.’

Returns: an ApiQuery of str

govtdesc()¶

A couple of sentences describing the nation’s government.

Example: ‘It is difficult to tell where the omnipresent government stops and the rest of society begins, but it juggles the competing demands of Defense, Environment, and Healthcare. It meets to discuss matters of state in the capital city of Test City.’

Returns: an ApiQuery of str

industrydesc()¶

A couple of sentences describing the nation’s economy, industry, and average income.

Example: ‘The strong Testlandish economy, worth a remarkable 2,212 trillion denarii a year, is driven almost entirely by government activity. The industrial sector, which is extremely specialized, is mostly made up of the Arms Manufacturing industry, with major contributions from Book Publishing. Average income is 73,510 denarii, with the richest citizens earning 6.0 times as much as the poorest.’

Returns: an ApiQuery of str

notable()¶

A few of nation’s peculiarities, at random.

Example: ‘museums and concert halls, multi-spousal wedding ceremonies, and devotion to social welfare’

Returns: an ApiQuery of str

sensibilities()¶

A couple of adjectives describing the nation’s citizens.

Example: ‘compassionate, devout’

Returns: an ApiQuery of str

population()¶

Nation’s population, in millions.

Returns: an ApiQuery of int

gdp()¶

Nation’s gross domestic product.

Returns: an ApiQuery of int

founded()¶

When the nation was founded.

1970-01-01 00:00 for nations founded in Antiquity.

Returns: an ApiQuery of a naive UTC datetime.datetime

firstlogin()¶

When the nation was first logged into.

1970-01-01 00:00 for nations first logged into during Antiquity.

Returns: an ApiQuery of a naive UTC datetime.datetime

lastlogin()¶

When the nation was last logged into.

Returns: an ApiQuery of a naive UTC datetime.datetime

wa()¶

Whether the nation is a member of the World Assembly or not.

Returns: an ApiQuery of WAMembership

freedom()¶

Nation’s Freedoms: three basic indicators of the nation’s Civil Rights, Economy, and Political Freedom, as expressive adjectives.

Returns: an ApiQuery of collections.OrderedDict with keys and values of str – Keys being, in order: Civil Rights, Economy, and Political Freedom.

freedomscores()¶

Nation’s Freedoms: three basic indicators of the nation’s Civil Rights, Economy, and Political Freedom, as percentages.

Returns: an ApiQuery of collections.OrderedDict with keys of str and values of int – Keys being, in order: Civil Rights, Economy, and Political Freedom.

govt()¶

Nation’s government expenditure, as percentages.

Returns: an ApiQuery of collections.OrderedDict with keys of str and values of float – Keys being, in order: Administration, Defense, Education, Environment, Healthcare, Industry, International Aid, Law & Order, Public Transport, Social Policy, Spirituality, and Welfare.

deaths()¶

Causes of death in the nation, as percentages.

Returns: an ApiQuery of dict with keys of str and values of float

endorsements()¶

Regional neighbours endorsing the nation.

Returns: an ApiQuery of a list of Nation

legislation()¶

Effects of the most recently passed legislation.

May contain HTML elements and character references.

Returns: an ApiQuery of a list of str

sectors()¶

Components of the nation’s economy, as percentages.

Returns: an ApiQuery of collections.OrderedDict with keys of str and values of float – Keys being, in order: Black Market (estimated), Government, Private Industry, and State-Owned Industry.

dispatchlist()¶

Nation’s published dispatches.

Returns: an ApiQuery of a list of DispatchThumbnail

policies()¶

Nation’s policies.

Returns: an ApiQuery of a list of Policy

zombie()¶

State during the annual Z-Day event.

Returns: an ApiQuery of Zombie

banners()¶

Nation’s visible banners. If the user has set a primary banner, it will be the first element in the list.

Returns: an ApiQuery of a list of str – URLs of the banner pictures.

census(*scales)¶

Current World Census data.

By default returns data on today’s featured World Census scale, use arguments to get results on specific scales. In order to request data on all scales at once you can do x.census(*range(81)).

Parameters: scales (int) – World Census scales, integers between 0 and 85 inclusive.
Returns: an ApiQuery of a list of CensusScaleCurrent

censushistory(*scales)¶

Historical World Census data.

Was split into its own method for the sake of simplicity.

By default returns data on today’s featured World Census scale, use arguments to get results on specific scales. In order to request data on all scales at once you can do x.censushistory(*range(81)).

Returns data for the entire length of history NationStates stores. There is no way to override that.

Parameters: scales (int) – World Census scales, integers between 0 and 85 inclusive.
Returns: an ApiQuery of a list of CensusScaleHistory

happenings()¶

Happenings archived on the in-game page. Newest to oldest.

These happenings are not parsed because they are subtly different from the ones in the normal feed and I see no practical use-cases for having them parsed as well.

Returns: an ApiQuery of a list of ArchivedHappening

async description()¶

Nation’s full description, as seen on its in-game page.

Returns: an awaitable of str

verification_url(*, token=None)¶

URL the user needs to follow in order to get the verification code for the nation.

Parameters: token (str) – A token specific to your service and the nation being verified.
Returns: str

verify(checksum, *, token=None)¶

Interface to the NationStates Verification API.

Parameters

checksum (str) – The user-supplied verification code. Expires if the nation logs out, if it performs a significant in-game action such as moving regions or endorsing another nation, and after it is successfully verified.
token (str) – A token specific to your service and the nation being verified.

Returns

an ApiQuery of bool

class NationControl(name, autologin='', password='')¶

Interface to the NationStates private Nation API. Subclasses Nation.

Credentials are not checked upon initialization, you will only know if you’ve made a mistake after you try to make the first request.

issues()¶

Issues the nation currently faces.

Returns: an ApiQuery of a list of Issue

Region shards¶

class Region(name)¶

A class to interact with the NationStates Region API.

id¶

The defining characteristic of a region, its normalized name. No two regions share the same id, and no one id is shared by multiple regions.

Type: str

url¶

URL of the region.

Type: str

name()¶

Name of the region, with proper capitalization.

Returns: an ApiQuery of str

flag()¶

URL of the region’s flag.

Returns: an ApiQuery of str

factbook()¶

Region’s World Factbook Entry.

Returns: an ApiQuery of str

power()¶

An adjective describing region’s power on the interregional scene.

Returns: an ApiQuery of str

delegatevotes()¶

Number of the votes in the World Assembly the region’s Delegate has.

Equal to the number of endorsements they have received.

Returns: an ApiQuery of int

numnations()¶

The number of nations in the region.

Returns: an ApiQuery of int

founded()¶

When the region was founded.

Returns: an ApiQuery of a naive UTC datetime.datetime

nations()¶

All the nations in the region.

Returns: an ApiQuery of a list of Nation objects

embassies()¶

Embassies the region has.

Returns: an ApiQuery of Embassies

embassyrmb()¶

Posting rights for members the of embassy regions.

Returns: an ApiQuery of EmbassyPostingRights

delegate()¶

Regional World Assembly Delegate.

Returns

an ApiQuery of Nation
an ApiQuery of None – If the region has no delegate.

delegateauth()¶

Regional World Assembly Delegate’s authority. Always set, no matter if the region has a delegate or not.

Returns: an ApiQuery of Authority

founder()¶

Regional Founder. Returned even if the nation has ceased to exist.

Returns

an ApiQuery of Nation
an ApiQuery of None – If the region is Game-Created and doesn’t have a founder.

founderauth()¶

Regional Founder’s authority. Always set, no matter if the region has a founder or not.

Returns: an ApiQuery of Authority

officers()¶

Regional Officers. Does not include the Founder or the Delegate, unless they have additional titles as Officers.

In the correct order.

Returns: an ApiQuery of a list of Officer

tags()¶

Tags the region has.

Returns: an ApiQuery of a list of str

zombie()¶

State during the annual Z-Day event.

Returns: an ApiQuery of Zombie

poll()¶

The poll currently running in the region.

Returns

an ApiQuery of Poll
an ApiQuery of None – If no poll is currently running.

census(*scales)¶

Current World Census data.

By default returns data on today’s featured World Census scale, use arguments to get results on specific scales. In order to request data on all scales at once you can do x.census(*range(81)).

Parameters: scales (int) – World Census scales, integers between 0 and 85 inclusive.
Returns: an ApiQuery of a list of CensusScaleCurrent

censushistory(*scales)¶

Historical World Census data.

Was split into its own method for the sake of simplicity.

By default returns data on today’s featured World Census scale, use arguments to get results on specific scales. In order to request data on all scales at once you can do x.censushistory(*range(81)).

Returns data for the entire length of history NationStates stores. There is no way to override that.

Parameters: scales (int) – World Census scales, integers between 0 and 85 inclusive.
Returns: an ApiQuery of a list of CensusScaleHistory

happenings()¶

Happenings archived on the in-game page. Newest to oldest.

These happenings are not parsed because they are subtly different from the ones in the normal feed and I see no practical use-cases for having them parsed as well.

Returns: an ApiQuery of a list of ArchivedHappening

World shards¶

class _World¶

Interface to the NationStates World API.

You shouldn’t build this object yourself, it is already provided to you at aionationstates.world.

featuredregion()¶

Today’s featured region.

Returns: an ApiQuery of Region

newnations()¶

Most recently founded nations, from newest.

Returns: an ApiQuery of a list of Nation

nations()¶

List of all the nations, seemingly in order of creation.

Returns: an ApiQuery of a list of Nation

numnations()¶

Total number of nations in the game.

Returns: an ApiQuery of int

regions()¶

List of all the regions, seemingly in order of creation.

Returns: an ApiQuery of a list of Region

numregions()¶

Total number of regions in the game.

Returns: an ApiQuery of int

regionsbytag(*tags)¶

All regions with any of the named tags.

Parameters: *tags (str) – Regional tags. Can be preceded by a - to select regions without that tag.
Returns: an ApiQuery of a list of Region

dispatch(id)¶

Dispatch by id.

Parameters: id (int) – Dispatch id.
Returns: an ApiQuery of Dispatch
Raises: NotFound – If a dispatch with the requested id doesn’t exist.

dispatchlist(*, author=None, category=None, subcategory=None, sort='new')¶

Find dispatches by certain criteria.

Parameters

author (str) – Name of the nation authoring the dispatch.
category (str) – Dispatch’s primary category.
subcategory (str) – Dispatch’s secondary category.
sort (str) – Sort order, ‘new’ or ‘best’.

Returns

an ApiQuery of a list of DispatchThumbnail

poll(id)¶

Poll with a given id.

Parameters: id (int) – Poll id.
Returns: an ApiQuery of Poll
Raises: NotFound – If a poll with the requested id doesn’t exist.

banner(*ids, _expand_macros=None)¶

Get data about banners by their ids.

Macros in banners’ names and descriptions are not expanded.

Parameters: *ids (str) – Banner ids.
Returns: an ApiQuery of a list of Banner
Raises: NotFound – If any of the provided ids is invalid.

tgqueue()¶

Count of currently enqueued recruitment telegrams.

Returns: TGQueue

census(*scales)¶

Current World Census data.

By default returns data on today’s featured World Census scale, use arguments to get results on specific scales. In order to request data on all scales at once you can do x.census(*range(81)).

Parameters: scales (int) – World Census scales, integers between 0 and 85 inclusive.
Returns: an ApiQuery of a list of CensusScaleCurrent

censushistory(*scales)¶

Historical World Census data.

Was split into its own method for the sake of simplicity.

By default returns data on today’s featured World Census scale, use arguments to get results on specific scales. In order to request data on all scales at once you can do x.censushistory(*range(81)).

Returns data for the entire length of history NationStates stores. There is no way to override that.

Parameters: scales (int) – World Census scales, integers between 0 and 85 inclusive.
Returns: an ApiQuery of a list of CensusScaleHistory

happenings(*, nations=None, regions=None, filters=None, beforeid=None, beforetime=None)¶

Iterate through happenings from newest to oldest.

Parameters

nations (iterable of str) – Nations happenings of which will be requested. Cannot be specified at the same time with regions.
regions (iterable of str) – Regions happenings of which will be requested. Cannot be specified at the same time with nations.
filters (iterable of str) – Categories to request happenings by. Available filters are: law, change, dispatch, rmb, embassy, eject, admin, move, founding, cte, vote, resolution, member, and endo.
beforeid (int) – Only request happenings before this id.
beforetime (datetime.datetime) – Only request happenings that were emitted before this moment.

Returns

an asynchronous iterator yielding any of the classes from the happenings module

new_happenings(poll_period=30, *, nations=None, regions=None, filters=None)¶

Iterate through new happenings as they arrive:

async for happening in \
        world.new_happenings(region='the north pacific'):
    # Your processing code here
    print(happening.text)  # As an example

Guarantees that:

Every happening is generated from the moment the generator is started;
No happening is generated more than once;
Happenings are generated in order from oldest to newest.

Parameters

poll_period (int) –
How long to wait between requesting the next portion of happenings, in seconds. Note that this should only be tweaked for latency reasons, as the function gives a guarantee that all happenings will be generated.

Also note that, regardless of the poll_period set, all of the code in your loop body still has to execute (likely several times) before a new portion of happenings can be requested. Consider wrapping your happening-processing code in a coroutine and launching it as a task from the loop body if you suspect this might become an issue.

Requests made by this generator are, of course, subject to the API rate limit, and if the limiter has to temporarily block new requests the time spent waiting will be added on top of poll_period.
nations (iterable of str) – Nations happenings of which will be requested. Cannot be specified at the same time with regions.
regions (iterable of str) – Regions happenings of which will be requested. Cannot be specified at the same time with nations.
filters (iterable of str) – Categories to request happenings by. Available filters are: law, change, dispatch, rmb, embassy, eject, admin, move, founding, cte, vote, resolution, member, and endo.

Returns

an asynchronous iterator yielding any of the classes from the happenings module

World Assembly shards¶

class _WA¶

General World Assembly shards.

You shouldn’t build this object yourself, it is already provided to you at aionationstates.wa.

numnations()¶

The number of nations in the World Assembly.

Returns: an ApiQuery of int

nations()¶

All the nations in the World Assembly.

Returns: an ApiQuery of a list of Nation objects

numdelegates()¶

The number of regional World Assembly delegates.

Returns: an ApiQuery of int

delegates()¶

All the regional World Assembly delegates.

Returns: an ApiQuery of a list of Nation objects

happenings()¶

Happenings archived on the in-game page. Newest to oldest.

These happenings are not parsed because they are subtly different from the ones in the normal feed and I see no practical use-cases for having them parsed as well.

Returns: an ApiQuery of a list of ArchivedHappening

proposals()¶

Resolution proposals.

Returns: ApiQuery of list of Proposal

resolution(index)¶

Resolution with a given index.

Parameters

index (int) –

Resolution index.

Global if this is the aionationstates.wa object, local if this is aionationstates.ga or aionationstates.sc.

Returns

ApiQuery of Resolution

Raises

NotFound – If a resolution with the requested index doesn’t exist.

class _WACouncil¶

World Assembly shards specific to a council.

You shouldn’t build these objects yourself, the instances are already provided to you at aionationstates.ga and aionationstates.sc.

resolution_at_vote()¶

The proposal currently being voted on.

Returns

ApiQuery of ResolutionAtVote
ApiQuery of None – If no resolution is currently at vote.

proposals()¶

Resolution proposals.

Returns: ApiQuery of list of Proposal

resolution(index)¶

Resolution with a given index.

Parameters

index (int) –

Resolution index.

Global if this is the aionationstates.wa object, local if this is aionationstates.ga or aionationstates.sc.

Returns

ApiQuery of Resolution

Raises

NotFound – If a resolution with the requested index doesn’t exist.

Data Classes¶

class CensusScaleCurrent¶

Current World Census scale data.

Warning

With the exception of score, you must not expect the fields to update instantly.

For the exact same reason of NationStates’ excessive quirkiness, those fields may be missing (set to None) on newly-founded nations (perhaps also in other cases, there is not a way to reliably test). You will need to account for that in your code.

Obviously, regions lack rrank and prrank, and the world only has score.

info¶

Static information about the scale.

Type: ScaleInfo

score¶

The absolute census score. All the other scale values are calculated (by NationStates) from scale scores of multiple nations. Should always be present.

Type: float

rank¶

World rank by the scale.

Type: int or None

prank¶

Percentage World rank by the scale.

Type: float or None

rrank¶

Regional rank by the scale.

Type: int or None

prrank¶

Percentage Regional rank by the scale.

Type: float or None

class CensusScaleHistory¶

Change of a World Census scale score through time.

info¶

Static information about the scale.

Type: ScaleInfo

history¶

The actual data.

Type: list of CensusPoint

class CensusPoint¶

A namedtuple of what the scale score was on a particular date.

timestamp¶

When the score was recorded.

Type: naive UTC datetime.datetime

score¶

What it was.

Type: float

class ScaleInfo¶

Static information about a World Census scale.

id¶

The scale id, an integer between 0 and 80 (84 if you also count Z-Day scales), inclusive.

Type: int

title¶

The scale title. For example, ‘Civil Rights’.

Type: str

ranked¶

A scale on which a nation or region is ranked, either in their region or the world. For example, ‘Most Extensive Civil Rights’.

Type: str

measurement¶

The measurement scale. For example, ‘Martin Luther King, Jr. Units’.

Type: str

image¶

An identifier NS uses for the Census tropy picture URLs.

Type: str

nation_description¶

Description for nations.

Type: str

region_description¶

Description for regions.

Type: str

class DispatchThumbnail¶

A dispatch thumbnail, missing text.

id¶

The dispatch id.

Type: int

title¶

The dispatch title.

Type: str

author¶

Nation that posted the dispatch.

Type: Nation

category¶

The dispatch category.

Type: str

subcategory¶

The dispatch subcategory.

Type: str

views¶

Number of times the dispatch got viewed.

Type: int

score¶

Number of votes the dispatch received.

Type: int

created¶

When the dispatch was created.

Type: naive UTC datetime.datetime

edited¶

When the dispatch last got edited. Equal to created for dispatches that were never edited.

Type: naive UTC datetime.datetime

class Dispatch¶

A full dispatch.

Includes all of the attributes of DispatchThumbnail, as well as:

text¶

The dispatch text.

Type: str

class Poll¶

A regional poll.

id¶

The poll id.

Type: int

title¶

The poll title.

Type: str

text¶

The poll text.

Type: str or None

region¶

Region the poll was posted in.

Type: Region

author¶

Nation that posted the poll.

Type: Nation

options¶

The poll options.

Type: list of PollOption

class PollOption¶

An option in a poll.

text¶

Text of the option.

Type: str

voters¶

Nations that picked this option.

Type: list of Nation

class WAMembership¶

Bases: enum.Enum

Nation’s World Assembly status.

Falsey when the nation doesn’t hold membership.

MEMBER¶

The nation is a member of the World Assembly.

Type: WAMembership

DELEGATE¶

The nation is a World Assembly Delegate of one of the regions.

Type: WAMembership

NONMEMBER¶

The nation is not a member of the World Assembly.

Type: WAMembership

class Policy¶

One of nation’s policies.

name¶

Name of the policy.

Type: str

category¶

Category of the policy.

Type: str

description¶

Short description of the policy.

Type: str

banner¶

URL of the policy picture.

Type: str

class Banner¶

A Rift banner.

id¶

The banner id.

Type: int

name¶

The banner name.

Type: str

validity¶

A requirement the nation has to meet in order to get the banner.

Type: str

class Issue¶

An issue.

id¶

The issue id.

Type: int

title¶

The issue title. May contain HTML elements and character references.

Type: str

text¶

The issue text. May contain HTML elements and character references.

Type: str

author¶

Author of the issue, usually the name of a nation.

Type: str

editor¶

Author of the issue, usually the name of a nation.

Type: str

options¶

Issue options.

Type: list of IssueOption

banners¶

URLs of issue banners.

Type: str

class IssueOption¶

An option of an issue.

text¶

The option text. May contain HTML elements and character references.

Type: str

class IssueResult¶

Outcome of an issue.

effect_line¶

The issue effect line. Not a sentence, mind you – it’s uncapitalized and does not end with a period. None if the issue was dismissed.

Type: str or None

census¶

Changes in census scores of the nation.

Type: list of CensusScaleChange

banners¶

The banners unlocked by answering the issue.

Type: list of Banner

new_policies¶

Policies introduced.

Type: list of Policy

removed_policies¶

Policies removed.

Type: list of Policy

reclassifications¶

All WA Category and Freedoms reclassifications listed, such as ‘Testlandia’s Civil Rights fell from Very Good to Good’, ‘Testlandia was reclassified from Inoffensive Centrist Democracy to Democratic Socialists’, etc..

Type: list of str

headlines¶

Newspaper headlines.

Type: list of str

class CensusScaleChange¶

Change in one of the World Census scales of a nation

info¶

Static information about the scale.

Type: ScaleInfo

score¶

The scale score, after the change.

Type: float

change¶

Change of the score.

Type: float

pchange¶

The semi-user-friendly percentage change NationStates shows by default.

Type: float

class Embassies¶

Embassies of a region.

active¶

Normal, alive embassies.

Type: list of Region

closing¶

Embassies the demolition of which has been initiated, but did not yet finish.

Type: list of Region

pending¶

Embassies the creation of which has been initiated, but did not yet finish.

Type: list of Region

invited¶

Embassy invitations that have not yet been processed.

Type: list of Region

rejected¶

Embassy invitations that have been denied.

Type: list of Region

class Officer¶

A Regional Officer.

nation¶

Officer’s nation.

Type: Nation

office¶

The (user-specified) office held by the officer.

Type: str

authority¶

Officer’s authority.

Type: Authority

appointed_at¶

When the officer got appointed.

Type: naive UTC datetime.datetime

appointed_by¶

The nation that appointed the officer.

Type: Nation

class Authority¶

Bases: enum.Flag

Authority of a Regional Officer, Delegate, or Founder.

X = EXECUTIVE

Can appoint/dismiss Officers and set their authority.

Type: Authority

W = WORLD_ASSEMBLY

Can approve World Assembly proposals.

Type: Authority

A = APPEARANCE

Can modify the World Factbook Entry, Flag, and Tags, and pin Dispatches.

Type: Authority

B = BORDER_CONTROL

Can eject/ban/unban nations and set/modify/remove the region password.

Type: Authority

C = COMMUNICATIONS

Can send region-wide telegrams without stamps, compose Welcome telegrams, suppress & unsuppress posts on the Regional Message Board, and control who can recruit for the region.

Type: Authority

E = EMBASSIES

Can open/close embassies with other regions and modify embassy posting privileges.

Type: Authority

P = POLLS

Can create polls.

Type: Authority

class EmbassyPostingRights¶

Bases: enum.Enum

Who out of embassy regions’ residents can post on the Regional Message Board.

Can be compared and ordered.

NOBODY¶

No members of the embassy regions can post.

Type: EmbassyPostingRights

DELEGATES_AND_FOUNDERS¶

Only the Founders and WA Delegates of embassy regions can post.

Type: EmbassyPostingRights

COMMUNICATIONS_OFFICERS¶

Only Regional Officers of embassy regions with the Communications authority can post.

Type: EmbassyPostingRights

OFFICERS¶

All Regional Officers of embassy regions can post.

Type: EmbassyPostingRights

EVERYBODY¶

All members of embassy regions can post.

Type: EmbassyPostingRights

class Post¶

A post on a Regional Message Board.

id¶

The unique id of the post.

Type: int

timestamp¶

When the post was put up.

Type: naive UTC datetime.datetime

author¶

The author nation.

Type: Nation

status¶

Status of the post.

Type: PostStatus

text¶

The post text.

Type: str

likers¶

Nations that liked the post.

Type: list of Nation

suppressor¶

Nation that suppressed the post. None if the post has not been suppressed or has been suppressed by moderators.

Type: Nation of None

class PostStatus¶

Bases: enum.Enum

Status of a post on a Regional Message Board.

NORMAL¶

A regular post.

Type: PostStatus

SUPPRESSED¶

The post got suppressed by a regional officer.

Type: PostStatus

DELETED¶

The post got deleted by its author.

Type: PostStatus

MODERATED¶

The post got suppressed by a game moderator.

Type: PostStatus

class Zombie¶

The situation in a nation/region during the annual Z-Day event.

survivors¶

The number of citizens surviving, in millions.

Type: int

zombies¶

The number of undead citizens, in millions.

Type: int

dead¶

The number of dead citizens, in millions.

Type: int

action¶

The nation’s strategy for dealing with the disaster. Either “research”, “exterminate”, or “export”. None if the instance represents regional situation.

Type: str or None

class TGQueue¶

Current length of recruinment telegram queues.

manual¶

Type: int

stamp¶

Type: int

api¶

Type: int

class ArchivedHappening¶

A happening from a national or regional archive.

timestamp¶

When the happening occured.

Type: naive UTC datetime.datetime

text¶

The happening text.

Type: str

class Proposal¶

A World Assembly proposal.

property approved_by¶

Delegates that approved this proposal.

Type: list of Nation

property url¶

URL to the proposal. Expires when the vote on the proposal starts, or when it expires.

Type: str

property author¶

The resolution author.

Type: Nation

property category¶

The resolution category.

Type: str

property council¶

General Assembly or Security Council.

Type: str

property id¶

The proposal id, for example la_navasse_1521428163.

Type: str

property name¶

Name of the resolution.

Type: str

property option¶

Whatever NationStates feels like. Somewhat like a subcategory sometimes, though not really. Sometimes represents resolution strength.

Type: str

repeal_target()¶

The resolution this resolution has repealed, or is attempting to repeal.

Returns: ApiQuery of Resolution
Raises: TypeError: – If the resolution doesn’t repeal anything.

property submitted¶

When the resolution was proposed.

Type: naive UTC datetime.datetime

property target¶

Target of a Liberation, Commendation, or Condemnation. None if the resolution is not a Liberation, Commendation, or Condemnation.

Type: Nation, Region, or None

property text¶

The resolution text. May contain BBCode.

Type: str

class Resolution¶

A World Assembly resolution.

property global_index¶

Index of the resolution irrespective of its councl.

Type: int

property local_index¶

Index of the resolution within its council.

Type: int

property implemented¶

When the resolution was voted into law.

Type: naive UTC datetime.datetime

property total_votes_for¶

Number of votes for the resolution, including delegate votes.

Type: int

property total_votes_against¶

Number of votes against the resolution, including delegate votes.

Type: int

property promoted¶

When the resolution was promoted to the voting floor.

Type: naive UTC datetime.datetime

property url¶

URL to the resolution.

Type: str

property author¶

The resolution author.

Type: Nation

property category¶

The resolution category.

Type: str

property council¶

General Assembly or Security Council.

Type: str

property id¶

The proposal id, for example la_navasse_1521428163.

Type: str

property name¶

Name of the resolution.

Type: str

property option¶

Whatever NationStates feels like. Somewhat like a subcategory sometimes, though not really. Sometimes represents resolution strength.

Type: str

repeal_target()¶

The resolution this resolution has repealed, or is attempting to repeal.

Returns: ApiQuery of Resolution
Raises: TypeError: – If the resolution doesn’t repeal anything.

property submitted¶

When the resolution was proposed.

Type: naive UTC datetime.datetime

property target¶

Target of a Liberation, Commendation, or Condemnation. None if the resolution is not a Liberation, Commendation, or Condemnation.

Type: Nation, Region, or None

property text¶

The resolution text. May contain BBCode.

Type: str

class VoteAction(value)¶

Bases: enum.Enum

How a nation votes on a resolution.

FOR¶

AGAINST¶

WITHDREW¶

class DelegateVoteLogEntry(elem)¶: An entry in the delegate vote log.

class VoteTrackEntry(for_, against, timestamp)¶

A collections.namedtuple of how many votes for & against the resolution had at a particular point in time.

for_¶

The number of votes for the resolution.

Type: int

against¶

The number of votes against the resolution.

Type: int

timestamp¶

When the above values were observed.

Type: datetime.datetime

class ResolutionAtVote¶

A World Assembly resolution at vote.

property total_votes_for¶

Number of votes for the resolution, including delegate votes.

Type: int

property total_votes_against¶

Number of votes against the resolution, including delegate votes.

Type: int

property nation_votes_for¶

Number of nations who voted for the resolution.

Type: int

property nation_votes_against¶

Number of nations who voted against the resolution.

Type: int

property promoted¶

When the resolution was promoted to the voting floor.

Type: naive UTC datetime.datetime

property delegate_vote_log¶

Log of the delegate votes.

Type: list of DelegateVoteLogEntry

property vote_track¶

Number of votes over time.

Type: list of VoteTrackEntry

property nations_voting_for¶

Nations who voted for the resolution. Chronological, includes delegates.

Type: list of Nation

property nations_voting_against¶

Nations who voted against the resolution. Chronological, includes delegates.

Type: list of Nation

property delegates_voting_for¶

Delegates who voted for the resolution and the number of votes they have.

In chronological order.

Type: list of (Nation, int) tuples

property delegates_voting_against¶

Delegates who voted against the resolution and the number of votes they have.

In chronological order.

Type: list of (Nation, int) tuples

property url¶

URL to the council the proposal is being voted on at. Expires when the vote on the proposal ends.

Type: str

property author¶

The resolution author.

Type: Nation

property category¶

The resolution category.

Type: str

property council¶

General Assembly or Security Council.

Type: str

property id¶

The proposal id, for example la_navasse_1521428163.

Type: str

property name¶

Name of the resolution.

Type: str

property option¶

Whatever NationStates feels like. Somewhat like a subcategory sometimes, though not really. Sometimes represents resolution strength.

Type: str

repeal_target()¶

The resolution this resolution has repealed, or is attempting to repeal.

Returns: ApiQuery of Resolution
Raises: TypeError: – If the resolution doesn’t repeal anything.

property submitted¶

When the resolution was proposed.

Type: naive UTC datetime.datetime

property target¶

Target of a Liberation, Commendation, or Condemnation. None if the resolution is not a Liberation, Commendation, or Condemnation.

Type: Nation, Region, or None

property text¶

The resolution text. May contain BBCode.

Type: str

Exceptions¶

exception RateLimitError¶

Raised when the request is forcibly terminated by NationStates due to a rate limit transgression.

(Or whenever the API returns with the HTTP status code 429.)

Generally, this should never happen under normal circumstances, as this library ensures compliance with the rate limits by default. However, there are factors the internal ratelimiter cannot account for, such as requests made outside of the current interpreter session, or just an exceptionally flaky network connection.

exception SessionConflictError¶

Raised when an authenticated request from NationControl is attempted despite the nation having been successfully logged into recently from elswhere.

(Or whenever the API returns with the HTTP status code 409.)

For any given nation, you should only ever maintain an authenticated session from one place at a time. Failure to do so will inevitably result in weirdness and wonkiness across the board. Not that you won’t get that anyway, but still.

exception AuthenticationError¶

Raised when the credentials provided to NationControl are incorrect.

(Or whenever the API returns with the HTTP status code 403 or the Web interface redirects to the login screen.)

exception NotFound¶

Raised when the requested nation or region doesn’t exist.

(Or whenever the API returns with the HTTP status code 404.)