API Documentation#

Note

For quicker navigation of this page, you can use the Table of Contents on the right sidebar.

Module Constants#

pyspl.__version__: str#

Returns a string with the format {major}.{minor}.{patch}, for example: 0.1.1.

Plays#

class pyspl.Play(description: str)#

A play script in the Shakespeare Programming Language (SPL). All programs made using PySPL must use this object.

add_act(act: Act, number: str, description: str)#

Adds an act to the play.

Parameters:

  • act (Act) – An Act object. Note that it should be an instance of a class, not the class itself.

  • number (str) – A roman numeral representing the order. PySPL does not actually consider this, it is here just for the SPL syntax.

  • description (str) – The description of the act. Must end with a period.

add_character(character: Character)#

Adds a character to the play.

Note

This function does NOT add the character onto the stage. Use Act.enter() for that purpose.

character(name: str, description: str) → Character#

Creates a character and adds it to the play.

This is equivalent to:

character = pyspl.Character(name, description)
play.add_character(character)
Returns:

The character created.

Return type:

Character

property characters: list[pyspl.character.Character]#

Returns a list of the characters in this play.

Return type:

list[Character]

code() → str#

Generates SPL code for this play.

Returns:

A piece of SPL code generated for this play.

Return type:

str

save(fn: str | bytes | PathLike, mode='w') → None#

Saves SPL code for this play into _fn_ using the mode specified.

Parameters:

  • fn (str) – The file to write to.

  • mode (str) – The mode to use for writing. Defaults to ‘w’.

Acts and Scenes#

class pyspl.Act(play: Play)#

Represents an act in a SPL play.

The recommended way is to subclass this object and create methods inside it, then add them by using Act.add_scene().

Example#

class Act1(pyspl.Act):
    def __init__(self):
        super().__init__(self, 'I', 'The First Act.')
        self.add_scene(sceneI)

    def scene1(self):
        # do whatever you need to do here
        pass
add_scene(func: Callable, number: str, description: str) → None#

Adds a scene to the act.

Parameters:

  • func (Callable) – The function of the scene to add.

  • number (str) – A roman numeral representing the number of the scene.

  • description (str) – The description of the scene. Must end with a period (AKA a full stop) (.).

enter(*characters: Character)#

Calls for the characters provided to enter the stage.

Parameters:

*characters (Character, ...) – The characters to enter the stage.

Raises:

StageLimitExceeded – There are too many characters on stage.

exit(*characters: Character)#

Calls for the characters provided to exit the stage.

Parameters:

*characters (Character, ...) – The characters to exit the stage. If not provided, all characters onstage will exit the stage.

Raises:

CharacterNotOnstage – The character who is trying to exit is not onstage.

input(target: ~pyspl.character.Character, type: type[str | int] = <class 'str'>)#

Receives input and sets the target to that value.

Parameters:

  • target (Character) – The character being set.

  • type – The type to receive. Defaults to str.

pop(target: Character)#

Pops an item from the target’s stack and set him/her to it.

Parameters:

target (Character) – The character to be modified.

print(target: ~pyspl.character.Character, type: type[str | int] = <class 'str'>)#

Prints the value of a character.

Parameters:

  • target (Character) – The character being printed.

  • type – The type to print. Defaults to str.

remember(target: Character, value: int | Operation | Character)#

Pushes the value onto the target’s stack.

Parameters:
set(target: Character, value: int | Operation | Character)#

Sets a character to a value.

Parameters:
Raises:
class pyspl.Scene(name: str, number: str, description: str)#

Represents a scene in a SPL play.

This is a data class.

Warning

This should not be constructed manually by the user. Instead, use Act.add_scene().

Characters#

class pyspl.Character(name: str, description: str)#

Represents a character in an SPL play.

Raises:

ValueError – The character name supplied is invalid.

Operations on Numbers#

class pyspl.Int(n: int)#

A number in SPL.

This shouldn’t be constructed manually by the user; instead just use the builtin int.

class pyspl.Operation#

A operation.

This is a base class for all operations.

class pyspl.sum(a: int | Operation | Character, b: int | Operation | Character)#

Represents the sum of a and b (\(a + b\))

class pyspl.difference(a: int | Operation | Character, b: int | Operation | Character)#

Represents the difference between a and b (\(a - b\)).

class pyspl.product(a: int | Operation | Character, b: int | Operation | Character)#

Represents the product of a and b (\(a \times b\)).

class pyspl.quotient(a: int | Operation | Character, b: int | Operation | Character)#

Represents the quotient of a and b (a // b).

class pyspl.remainder(a: int | Operation | Character, b: int | Operation | Character)#

Represents the remainder of the quotient of a and b (a % b).

class pyspl.square(x: int | Operation | Character)#

Represents the square of x (\(x^2\)).

class pyspl.cube(x: int | Operation | Character)#

Represents the cube of x (\(x^3\)).

class pyspl.squareroot(x: int | Operation | Character)#

Represents the square root of x (\(\sqrt{x}\)).

class pyspl.factorial(x: int | Operation | Character)#

Represents the factorial of x (\(x!\)).

Errors#

class pyspl.StageLimitExceeded#

Raised when the maximum number of characters on stage (which is 2) is exceeded.

class pyspl.InvalidNumberError#

Raised when a number supplied in operations (Play.sum(), Play.difference(), and so on) is invalid.

The cause is usually because of the number not being a power of 2.

class pyspl.CharacterNotOnstage#

Raised when an operation is trying to be done on a character who is not onstage.

class pyspl.NotEnoughCharacters#

Raised when there is only one character onstage.

That does not work because you need a character to set or print another character’s value.