diff --git a/assets/src/ba_data/python/ba/__init__.py b/assets/src/ba_data/python/ba/__init__.py index ef418c72..3435ad09 100644 --- a/assets/src/ba_data/python/ba/__init__.py +++ b/assets/src/ba_data/python/ba/__init__.py @@ -24,7 +24,6 @@ This top level module is a collection of most commonly used functionality. For many modding purposes, the bits exposed here are all you'll need. In some specific cases you may need to pull in individual submodules instead. """ - # pylint: disable=unused-import # pylint: disable=redefined-builtin @@ -74,7 +73,7 @@ from ba._apputils import is_browser_likely_available from ba._campaign import Campaign from ba._gameutils import (animate, animate_array, show_damage_count, sharedobj, timestring, cameraflash) -from ba._general import WeakCall, Call, existing +from ba._general import WeakCall, Call, existing, Existable from ba._level import Level from ba._lobby import Lobby, Chooser from ba._math import normalized_color, is_point_in_box, vec3validate diff --git a/assets/src/ba_data/python/ba/_general.py b/assets/src/ba_data/python/ba/_general.py index a535b00d..159c6561 100644 --- a/assets/src/ba_data/python/ba/_general.py +++ b/assets/src/ba_data/python/ba/_general.py @@ -24,28 +24,32 @@ from __future__ import annotations import types import weakref from typing import TYPE_CHECKING, TypeVar +from typing_extensions import Protocol import _ba if TYPE_CHECKING: from typing import Any, Type, Optional - from typing_extensions import Protocol from efro.call import Call as Call # 'as Call' so we re-export. - class Existable(Protocol): - """Protocol for objects supporting an exists() method.""" - def exists(self) -> bool: - """Whether this object exists.""" - ... +class Existable(Protocol): + """A Protocol for objects supporting an exists() method. - ExistableType = TypeVar('ExistableType', bound=Existable) + Category: Protocols + """ + def exists(self) -> bool: + """Whether this object exists.""" + ... + + +ExistableType = TypeVar('ExistableType', bound=Existable) T = TypeVar('T') def existing(obj: Optional[ExistableType]) -> Optional[ExistableType]: - """Convert invalid references to None. + """Convert invalid references to None for any ba.Existable type. Category: Gameplay Functions diff --git a/config/config.json b/config/config.json index db5e30f5..d3c4e230 100644 --- a/config/config.json +++ b/config/config.json @@ -11,7 +11,8 @@ "pytest", "pytz", "yaml", - "requests" + "requests", + "typing_extensions" ], "python_paths": [ "assets/src/ba_data/python", diff --git a/docs/ba_module.md b/docs/ba_module.md index 1ae1ec10..2e8fdb04 100644 --- a/docs/ba_module.md +++ b/docs/ba_module.md @@ -1,5 +1,5 @@ -

last updated on 2020-05-21 for Ballistica version 1.5.0 build 20026

+

last updated on 2020-05-22 for Ballistica version 1.5.0 build 20026

This page documents the Python classes and functions in the 'ba' module, which are the ones most relevant to modding in Ballistica. If you come across something you feel should be included here or could be better explained, please let me know. Happy modding!

@@ -200,6 +200,10 @@
  • ba.WidgetNotFoundError
    • +

    Protocols

    +

    ba.Achievement

    <top level class> @@ -320,7 +324,7 @@ actually award achievements.

    ba.Activity

    -

    inherits from: ba.DependencyComponent, typing.Generic

    +

    Inherits from: ba.DependencyComponent, typing.Generic

    Units of execution wrangled by a ba.Session.

    Category: Gameplay Classes

    @@ -570,7 +574,7 @@ is a convenient way to access this same functionality.

    ba.ActivityNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.Activity does not exist.

    Category: Exception Classes @@ -733,7 +737,7 @@ likely result in errors.

    ba.ActorNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.Actor does not exist.

    Category: Exception Classes @@ -949,7 +953,7 @@ to resume.

    ba.AppConfig

    -

    inherits from: dict

    +

    Inherits from: dict

    A special dict that holds the game's persistent configuration values.

    Category: App Classes

    @@ -1063,7 +1067,7 @@ when done.

    ba.AssetPackage

    -

    inherits from: ba.DependencyComponent

    +

    Inherits from: ba.DependencyComponent

    ba.DependencyComponent representing a bundled package of game assets.

    Category: Asset Classes @@ -1465,7 +1469,7 @@ start_long_action(callback_when_done=ba.ContextC

    ba.CoopGameActivity

    -

    inherits from: ba.GameActivity, ba.Activity, ba.DependencyComponent, typing.Generic

    +

    Inherits from: ba.GameActivity, ba.Activity, ba.DependencyComponent, typing.Generic

    Base class for cooperative-mode games.

    Category: Gameplay Classes @@ -1581,7 +1585,7 @@ and it should begin its actual game logic.

    ba.CoopSession

    -

    inherits from: ba.Session

    +

    Inherits from: ba.Session

    A ba.Session which runs cooperative-mode games.

    Category: Gameplay Classes

    @@ -1669,7 +1673,7 @@ the data object is requested and when it's value is accessed.

    ba.DeathType

    -

    inherits from: enum.Enum

    +

    Inherits from: enum.Enum

    A reason for a death.

    Category: Enums @@ -1686,7 +1690,7 @@ the data object is requested and when it's value is accessed.

    ba.Dependency

    -

    inherits from: typing.Generic

    +

    Inherits from: typing.Generic

    A dependency on a DependencyComponent (with an optional config).

    Category: Dependency Classes

    @@ -1759,7 +1763,7 @@ on the dep config value. (for instance a map required by a game type)

    ba.DependencyError

    -

    inherits from: Exception, BaseException

    +

    Inherits from: Exception, BaseException

    Exception raised when one or more ba.Dependency items are missing.

    Category: Exception Classes

    @@ -1786,7 +1790,7 @@ on the dep config value. (for instance a map required by a game type)

    ba.DependencySet

    -

    inherits from: typing.Generic

    +

    Inherits from: typing.Generic

    Set of resolved dependencies and their associated data.

    Category: Dependency Classes

    @@ -1918,7 +1922,7 @@ its time with lingering corpses, sound effects, etc.

    ba.DualTeamSession

    -

    inherits from: ba.MultiTeamSession, ba.Session

    +

    Inherits from: ba.MultiTeamSession, ba.Session

    ba.Session type for teams mode games.

    Category: Gameplay Classes @@ -1935,11 +1939,28 @@ its time with lingering corpses, sound effects, etc.

    Set up playlists and launches a ba.Activity to accept joiners.

    + + +
    +

    ba.Existable

    +

    Inherits from: typing_extensions.Protocol

    +

    A Protocol for objects supporting an exists() method.

    + +

    Category: Protocols +

    + +

    Methods:

    +
    +

    exists()

    +

    exists(self) -> bool

    + +

    Whether this object exists.

    +

    ba.FreeForAllSession

    -

    inherits from: ba.MultiTeamSession, ba.Session

    +

    Inherits from: ba.MultiTeamSession, ba.Session

    ba.Session type for free-for-all mode games.

    Category: Gameplay Classes @@ -1987,7 +2008,7 @@ its time with lingering corpses, sound effects, etc.

    ba.GameActivity

    -

    inherits from: ba.Activity, ba.DependencyComponent, typing.Generic

    +

    Inherits from: ba.Activity, ba.DependencyComponent, typing.Generic

    Common base class for all game ba.Activities.

    Category: Gameplay Classes @@ -2591,7 +2612,7 @@ prefs, etc.

    ba.InputDeviceNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.InputDevice does not exist.

    Category: Exception Classes @@ -2884,7 +2905,7 @@ etc.

    ba.Map

    -

    inherits from: ba.Actor

    +

    Inherits from: ba.Actor

    A game map.

    Category: Gameplay Classes

    @@ -3240,7 +3261,7 @@ Use ba.getmodel() to instantiate one.

    ba.MultiTeamSession

    -

    inherits from: ba.Session

    +

    Inherits from: ba.Session

    Common base class for ba.DualTeamSession and ba.FreeForAllSession.

    Category: Gameplay Classes

    @@ -3404,7 +3425,7 @@ signify that the default soundtrack should be used..

    ba.MusicPlayMode

    -

    inherits from: enum.Enum

    +

    Inherits from: enum.Enum

    Influences behavior when playing music.

    Category: Enums @@ -3417,7 +3438,7 @@ signify that the default soundtrack should be used..

    ba.MusicType

    -

    inherits from: enum.Enum

    +

    Inherits from: enum.Enum

    Types of music available to play in-game.

    Category: Enums

    @@ -3559,7 +3580,7 @@ acting as an alternative to setting node attributes.

    ba.NodeActor

    -

    inherits from: ba.Actor

    +

    Inherits from: ba.Actor

    A simple ba.Actor type that wraps a single ba.Node.

    Category: Gameplay Classes

    @@ -3626,7 +3647,7 @@ even if myactor is set to None.

    ba.NodeNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.Node does not exist.

    Category: Exception Classes @@ -3636,7 +3657,7 @@ even if myactor is set to None.

    <all methods inherited from ba.NotFoundError>

    ba.NotFoundError

    -

    inherits from: Exception, BaseException

    +

    Inherits from: Exception, BaseException

    Exception raised when a referenced object does not exist.

    Category: Exception Classes @@ -3662,7 +3683,7 @@ even if myactor is set to None.

    ba.Permission

    -

    inherits from: enum.Enum

    +

    Inherits from: enum.Enum

    Permissions that can be requested from the OS.

    Category: Enums @@ -3720,7 +3741,7 @@ even if myactor is set to None.

    ba.Player

    -

    inherits from: typing.Generic

    +

    Inherits from: typing.Generic

    A player in a specific ba.Activity.

    Category: Gameplay Classes

    @@ -3879,7 +3900,7 @@ the type-checker properly identifies the returned value as one.

    ba.PlayerNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.Player does not exist.

    Category: Exception Classes @@ -4097,7 +4118,7 @@ change this. Defaults to an empty string.

    ba.ScoreType

    -

    inherits from: enum.Enum

    +

    Inherits from: enum.Enum

    Type of scores.

    Category: Enums @@ -4348,7 +4369,7 @@ session.set_activity(foo) and then ba.newnode

    ba.SessionNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.Session does not exist.

    Category: Exception Classes @@ -4513,7 +4534,7 @@ other players.

    ba.SessionPlayerNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.SessionPlayer does not exist.

    Category: Exception Classes @@ -4586,7 +4607,7 @@ of the session.

    ba.SessionTeamNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.SessionTeam does not exist.

    Category: Exception Classes @@ -4622,7 +4643,7 @@ of the session.

    ba.SpecialChar

    -

    inherits from: enum.Enum

    +

    Inherits from: enum.Enum

    Special characters the game can print.

    Category: Enums @@ -4829,7 +4850,7 @@ of the session.

    ba.Team

    -

    inherits from: typing.Generic

    +

    Inherits from: typing.Generic

    A team in a specific ba.Activity.

    Category: Gameplay Classes

    @@ -4859,7 +4880,7 @@ of the session.

    ba.TeamGameActivity

    -

    inherits from: ba.GameActivity, ba.Activity, ba.DependencyComponent, typing.Generic

    +

    Inherits from: ba.GameActivity, ba.Activity, ba.DependencyComponent, typing.Generic

    Base class for teams and free-for-all mode games.

    Category: Gameplay Classes

    @@ -5074,7 +5095,7 @@ Results for a completed ba.TeamGameActivity

    ba.TeamNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.Team does not exist.

    Category: Exception Classes @@ -5110,7 +5131,7 @@ Results for a completed ba.TeamGameActivity

    ba.TimeFormat

    -

    inherits from: enum.Enum

    +

    Inherits from: enum.Enum

    Specifies the format time values are provided in.

    Category: Enums @@ -5188,7 +5209,7 @@ self.t = ba.Timer(0.3, say_it, repeat=True)

    ba.TimeType

    -

    inherits from: enum.Enum

    +

    Inherits from: enum.Enum

    Specifies the type of time for various operations to target/use.

    Category: Enums

    @@ -5427,7 +5448,7 @@ widgets.

    ba.WidgetNotFoundError

    -

    inherits from: ba.NotFoundError, Exception, BaseException

    +

    Inherits from: ba.NotFoundError, Exception, BaseException

    Exception raised when an expected ba.Widget does not exist.

    Category: Exception Classes @@ -5698,7 +5719,7 @@ settings, exiting element counts, or other factors.

    ba.existing()

    existing(obj: Optional[ExistableType]) -> Optional[ExistableType]

    -

    Convert invalid references to None.

    +

    Convert invalid references to None for any ba.Existable type.

    Category: Gameplay Functions

    diff --git a/tools/efrotools/code.py b/tools/efrotools/code.py index 4d921ab2..bc6a4eb7 100644 --- a/tools/efrotools/code.py +++ b/tools/efrotools/code.py @@ -374,7 +374,7 @@ def _run_pylint(projroot: Path, pylintrc: Union[Path, str], result = _apply_pylint_run_to_cache(projroot, run, dirtyfiles, allfiles, cache) if result != 0: - raise CleanError(f'Linting failed for {result} file(s).') + raise CleanError(f'Pylint failed for {result} file(s).') # Sanity check: when the linter fails we should always be failing too. # If not, it means we're probably missing something and incorrectly @@ -400,6 +400,7 @@ def _apply_pylint_run_to_cache(projroot: Path, run: Any, dirtyfiles: List[str], # pylint: disable=too-many-statements from astroid import modutils from efrotools import get_config + from efro.error import CleanError # First off, build a map of dirtyfiles to module names # (and the corresponding reverse map). @@ -456,8 +457,8 @@ def _apply_pylint_run_to_cache(projroot: Path, run: Any, dirtyfiles: List[str], untracked_deps = set(dep for dep in untracked_deps if dep not in ignored_untracked_deps) if untracked_deps: - raise Exception( - f'Found untracked dependencies: {untracked_deps}.' + raise CleanError( + f'Pylint found untracked dependencies: {untracked_deps}.' ' If these are external to your project, add them to' ' "pylint_ignored_untracked_deps" in the project config.') @@ -552,7 +553,7 @@ def mypy(projroot: Path, full: bool) -> None: try: runmypy(projroot, filenames, full) except Exception: - raise CleanError('Mypy: fail.') + raise CleanError('Mypy failed.') duration = time.time() - starttime print(f'{Clr.GRN}Mypy passed in {duration:.1f} seconds.{Clr.RST}', flush=True) diff --git a/tools/efrotools/snippets.py b/tools/efrotools/snippets.py index d2f206ba..12e07cea 100644 --- a/tools/efrotools/snippets.py +++ b/tools/efrotools/snippets.py @@ -248,33 +248,22 @@ def scriptfiles() -> None: def pylint() -> None: """Run pylint checks on our scripts.""" - from efro.error import CleanError import efrotools.code full = ('-full' in sys.argv) fast = ('-fast' in sys.argv) - try: - efrotools.code.pylint(PROJROOT, full, fast) - except Exception: - raise CleanError('Pylint failed.') + efrotools.code.pylint(PROJROOT, full, fast) def runpylint() -> None: """Run pylint checks on provided filenames.""" - import os from efro.terminal import Clr from efro.error import CleanError import efrotools.code if len(sys.argv) < 3: raise CleanError('Expected at least 1 filename arg.') filenames = sys.argv[2:] - try: - efrotools.code.runpylint(PROJROOT, filenames) - print(f'{Clr.GRN}Pylint Passed.{Clr.RST}') - except Exception: - if os.environ.get('VERBOSE') == '1': - import traceback - traceback.print_exc() - raise CleanError('Pylint Failed.') + efrotools.code.runpylint(PROJROOT, filenames) + print(f'{Clr.GRN}Pylint Passed.{Clr.RST}') def mypy() -> None: