From 86f9176f711b2d1f7cb2c7290fdfa48436994d20 Mon Sep 17 00:00:00 2001 From: Perry Goy Date: Tue, 30 Apr 2024 16:10:10 -0500 Subject: [PATCH] Remove unnecessary paths from Sphinx directives. (#132) * remove unnecessary paths from Sphinx directives. * remove full alias autodoc from documentation. * work around mypy issue https://github.com/python/mypy/issues/6700. --- docs/api/actions.rst | 39 ++++++------ docs/api/actors.rst | 7 +++ screenpy/actions/either.py | 48 +++++++-------- screenpy/actions/eventually.py | 30 +++------ screenpy/actions/make_note.py | 7 ++- screenpy/actions/pause.py | 6 +- screenpy/actor.py | 108 +++++++++------------------------ tests/test_actions.py | 8 +-- 8 files changed, 97 insertions(+), 156 deletions(-) diff --git a/docs/api/actions.rst b/docs/api/actions.rst index 731c08d3..c3cf181b 100644 --- a/docs/api/actions.rst +++ b/docs/api/actions.rst @@ -24,11 +24,30 @@ Debug .. autoclass:: Debug :members: +Either +------ + +**Aliases**: ``Attempt``, +``AttemptTo``, +``GoFor``, +``Try`` +``TryTo``, +``Attempts``, +``AttemptsTo``, +``GoesFor``, +``Tries``, +``TriesTo`` + +.. autoclass:: Either + :members: + :exclude-members: except_, else_, otherwise, alternatively, failing_that + Eventually ---------- .. autoclass:: Eventually :members: + :exclude-members: trying_for_no_longer_than, trying_for, waiting_for, polling_every, trying_every Log --- @@ -45,6 +64,7 @@ MakeNote .. autoclass:: MakeNote :members: + :exclude-members: of_the Pause ----- @@ -55,6 +75,7 @@ Pause .. autoclass:: Pause :members: + :exclude-members: second_because, See --- @@ -112,21 +133,3 @@ Silently **Aliases**: ``Quietly`` .. autofunction:: Silently - - -Either ------- - -**Aliases**: ``Attempt``, -``AttemptTo``, -``GoFor``, -``Try`` -``TryTo``, -``Attempts``, -``AttemptsTo``, -``GoesFor``, -``Tries``, -``TriesTo`` - -.. autoclass:: Either - :members: diff --git a/docs/api/actors.rst b/docs/api/actors.rst index e80cbb95..2504fced 100644 --- a/docs/api/actors.rst +++ b/docs/api/actors.rst @@ -4,3 +4,10 @@ Actor API .. autoclass:: screenpy.actor.Actor :members: + :exclude-members: + can, + with_ordered_cleanup_tasks, with_independent_cleanup_tasks, + ability_to, + was_able_to, did, will, tries_to, tried_to, tries, tried, does, should, shall + perform, + exit_stage_left, exit_stage_right, exit_through_vomitorium diff --git a/screenpy/actions/either.py b/screenpy/actions/either.py index b6f556b9..0268f884 100644 --- a/screenpy/actions/either.py +++ b/screenpy/actions/either.py @@ -25,7 +25,7 @@ class Either: By default, ``Either`` catches AssertionErrors, so you can use :class:`~screenpy.actions.See` to decide which path to follow. Use the - :meth:`~screenpy.actions.Either.ignoring` method to ignore other exceptions. + :meth:`ignoring` method to ignore other exceptions. Examples:: @@ -46,33 +46,15 @@ class Either: except_performables: tuple[Performable, ...] ignore_exceptions: tuple[type[BaseException], ...] - def perform_as(self, the_actor: Actor) -> None: - """Direct the Actor to perform one of two performances.""" - # kinking the cable before the attempt - # avoids explaning what the actor tries to do. - # logs the first attempt only if it succeeds - # or if UNABRIDGED_NARRATION is enabled - with the_narrator.mic_cable_kinked(): - try: - the_actor.will(*self.try_performables) - except self.ignore_exceptions: - if not settings.UNABRIDGED_NARRATION: - the_narrator.clear_backup() - else: - return - - the_actor.will(*self.except_performables) - return - def or_(self, *except_performables: Performable) -> Self: """Provide the alternative routine to perform. Aliases: - * :meth:`~screenpy.actions.Either.except_` - * :meth:`~screenpy.actions.Either.else_` - * :meth:`~screenpy.actions.Either.otherwise` - * :meth:`~screenpy.actions.Either.alternatively` - * :meth:`~screenpy.actions.Either.failing_that` + * ``except_`` + * ``else_`` + * ``otherwise`` + * ``alternatively`` + * ``failing_that`` """ self.except_performables = except_performables return self @@ -95,6 +77,24 @@ def describe(self) -> str: return f"Either {try_summary} or {except_summary}" + def perform_as(self, the_actor: Actor) -> None: + """Direct the Actor to perform one of two performances.""" + # kinking the cable before the attempt + # avoids explaning what the actor tries to do. + # logs the first attempt only if it succeeds + # or if UNABRIDGED_NARRATION is enabled + with the_narrator.mic_cable_kinked(): + try: + the_actor.will(*self.try_performables) + except self.ignore_exceptions: + if not settings.UNABRIDGED_NARRATION: + the_narrator.clear_backup() + else: + return + + the_actor.will(*self.except_performables) + return + def __init__(self, *first: Performable) -> None: self.try_performables: tuple[Performable, ...] = first self.ignore_exceptions = (AssertionError,) diff --git a/screenpy/actions/eventually.py b/screenpy/actions/eventually.py index 89b463f5..3dbdf0da 100644 --- a/screenpy/actions/eventually.py +++ b/screenpy/actions/eventually.py @@ -81,41 +81,25 @@ def for_(self, amount: float) -> _TimeframeBuilder: """Set for how long the actor should continue trying. Aliases: - * :meth:`~screenpy.actions.Eventually.trying_for_no_longer_than` - * :meth:`~screenpy.actions.Eventually.trying_for` - * :meth:`~screenpy.actions.Eventually.waiting_for` + * ``trying_for_no_longer_than`` + * ``trying_for`` + * ``waiting_for`` """ return self._TimeframeBuilder(self, amount, "timeout") - def trying_for_no_longer_than(self, amount: float) -> _TimeframeBuilder: - """Alias for :meth:`~screenpy.actions.Eventually.for_`.""" - return self.for_(amount) - - def trying_for(self, amount: float) -> _TimeframeBuilder: - """Alias for :meth:`~screenpy.actions.Eventually.for_`.""" - return self.for_(amount) - - def waiting_for(self, amount: float) -> _TimeframeBuilder: - """Alias for :meth:`~screenpy.actions.Eventually.for_`.""" - return self.for_(amount) + trying_for_no_longer_than = trying_for = waiting_for = for_ def polling(self, amount: float) -> _TimeframeBuilder: """Adjust the polling frequency. Aliases: - * :meth:`~screenpy.actions.Eventually.polling_every` - * :meth:`~screenpy.actions.Eventually.trying_every` + * ``polling_every`` + * ``trying_every`` """ self.poll = amount return self._TimeframeBuilder(self, amount, "poll") - def polling_every(self, amount: float) -> _TimeframeBuilder: - """Alias for :meth:`~screenpy.actions.Eventually.polling`.""" - return self.polling(amount) - - def trying_every(self, amount: float) -> _TimeframeBuilder: - """Alias for :meth:`~screenpy.actions.Eventually.polling`.""" - return self.polling(amount) + polling_every = trying_every = polling @property def performable_to_log(self) -> str: diff --git a/screenpy/actions/make_note.py b/screenpy/actions/make_note.py index c1dc07b9..1e038d60 100644 --- a/screenpy/actions/make_note.py +++ b/screenpy/actions/make_note.py @@ -44,13 +44,16 @@ def of(cls, question: T_Q) -> Self: """Supply the Question to answer and its arguments. Aliases: - * :meth:`~screenpy.actions.MakeNote.of_the` + * ``of_the`` """ return cls(question) @classmethod def of_the(cls, question: T_Q) -> Self: - """Alias for :meth:`~screenpy.actions.MakeNote.of`.""" + """Alias for :meth:`of`. + + Workaround for https://github.com/python/mypy/issues/6700 + """ return cls.of(question) def as_(self, key: str) -> Self: diff --git a/screenpy/actions/pause.py b/screenpy/actions/pause.py index 421b37ea..5568f553 100644 --- a/screenpy/actions/pause.py +++ b/screenpy/actions/pause.py @@ -50,15 +50,13 @@ def seconds_because(self, reason: str) -> Self: """Use seconds and provide a reason for the pause. Aliases: - * :meth:`~screenpy.actions.Pause.second_because` + * ``second_because`` """ self.unit = f"second{'s' if self.number != 1 else ''}" self.reason = self._massage_reason(reason) return self - def second_because(self, reason: str) -> Self: - """Alias for :meth:`~screenpy.actions.Pause.seconds_because`.""" - return self.seconds_because(reason) + second_because = seconds_because def milliseconds_because(self, reason: str) -> Self: """Use milliseconds and provide a reason for the pause.""" diff --git a/screenpy/actor.py b/screenpy/actor.py index 83133cba..02081b4d 100644 --- a/screenpy/actor.py +++ b/screenpy/actor.py @@ -68,14 +68,12 @@ def who_can(self, *abilities: T_Ability) -> Self: """Add one or more Abilities to this Actor. Aliases: - * :meth:`~screenpy.actor.Actor.can` + * ``can`` """ self.abilities.extend(abilities) return self - def can(self, *abilities: T_Ability) -> Self: - """Alias for :meth:`~screenpy.actor.Actor.who_can`.""" - return self.who_can(*abilities) + can = who_can def has_ordered_cleanup_tasks(self, *tasks: Performable) -> Self: """Assign one or more tasks for the Actor to perform when exiting. @@ -85,14 +83,12 @@ def has_ordered_cleanup_tasks(self, *tasks: Performable) -> Self: and will be discarded. Aliases: - * :meth:`~screenpy.actor.Actor.with_ordered_cleanup_tasks` + * ``with_ordered_cleanup_tasks`` """ self.ordered_cleanup_tasks.extend(tasks) return self - def with_ordered_cleanup_tasks(self, *tasks: Performable) -> Self: - """Alias for :meth:`~screenpy.actor.Actor.has_ordered_cleanup_tasks`.""" - return self.has_ordered_cleanup_tasks(*tasks) + with_ordered_cleanup_tasks = has_ordered_cleanup_tasks def has_independent_cleanup_tasks(self, *tasks: Performable) -> Self: """Assign one or more tasks for the Actor to perform when exiting. @@ -102,14 +98,12 @@ def has_independent_cleanup_tasks(self, *tasks: Performable) -> Self: previous ones were successful. Aliases: - * :meth:`~screenpy.actor.Actor.with_independent_cleanup_tasks` + * ``with_independent_cleanup_tasks`` """ self.independent_cleanup_tasks.extend(tasks) return self - def with_independent_cleanup_tasks(self, *tasks: Performable) -> Self: - """Alias for :meth:`~screenpy.actor.Actor.has_independent_cleanup_tasks`.""" - return self.has_independent_cleanup_tasks(*tasks) + with_independent_cleanup_tasks = has_independent_cleanup_tasks def uses_ability_to(self, ability: type[T_Ability]) -> T_Ability: """Find the Ability referenced and return it, if the Actor is capable. @@ -118,7 +112,7 @@ def uses_ability_to(self, ability: type[T_Ability]) -> T_Ability: UnableToPerform: the Actor doesn't possess the Ability. Aliases: - * :meth:`~screenpy.actor.Actor.ability_to` + * ``ability_to`` """ for a in self.abilities: if isinstance(a, ability): @@ -127,9 +121,7 @@ def uses_ability_to(self, ability: type[T_Ability]) -> T_Ability: msg = f"{self} does not have the Ability to {ability}" raise UnableToPerform(msg) - def ability_to(self, ability: type[T_Ability]) -> T_Ability: - """Alias for :meth:`~screenpy.actor.Actor.uses_ability_to`.""" - return self.uses_ability_to(ability) + ability_to = uses_ability_to def has_ability_to(self, ability: type[T_Ability]) -> bool: """Ask whether the Actor has the Ability to do something.""" @@ -144,59 +136,23 @@ def attempts_to(self, *actions: Performable) -> None: """Perform a list of Actions, one after the other. Aliases: - * :meth:`~screenpy.actor.Actor.was_able_to` - * :meth:`~screenpy.actor.Actor.should` - * :meth:`~screenpy.actor.Actor.shall` - * :meth:`~screenpy.actor.Actor.will` - * :meth:`~screenpy.actor.Actor.tries_to` - * :meth:`~screenpy.actor.Actor.tried_to` - * :meth:`~screenpy.actor.Actor.tries` - * :meth:`~screenpy.actor.Actor.tried` - * :meth:`~screenpy.actor.Actor.does` - * :meth:`~screenpy.actor.Actor.did` + * ``was_able_to`` + * ``did`` + * ``will`` + * ``tries_to`` + * ``tried_to`` + * ``tries`` + * ``tried`` + * ``does`` + * ``should`` + * ``shall`` """ for action in actions: self.perform(action) - def was_able_to(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def tries_to(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def tried_to(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def tries(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def tried(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def does(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def did(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def will(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def shall(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) - - def should(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" - return self.attempts_to(*actions) + was_able_to = did = attempts_to + tries_to = tried_to = tries = tried = does = will = attempts_to + shall = should = attempts_to def perform(self, action: Performable) -> None: """Perform an Action.""" @@ -231,32 +187,22 @@ def cleans_up(self) -> None: self.cleans_up_ordered_tasks() def exit(self) -> None: - """Direct the Actor to forget all their Abilities. + """Direct the Actor to clean up and forget all their Abilities. Aliases: - * :meth:`~screenpy.actor.Actor.exit_stage_left` - * :meth:`~screenpy.actor.Actor.exit_stage_right` - * :meth:`~screenpy.actor.Actor.exit_through_vomitorium` + * ``exit_stage_left`` + * ``exit_stage_right`` + * ``exit_through_vomitorium`` """ self.cleans_up() for ability in self.abilities: ability.forget() self.abilities = [] - def exit_stage_left(self) -> None: - """Alias for :meth:`~screenpy.actor.Actor.exit`.""" - return self.exit() - - def exit_stage_right(self) -> None: - """Alias for :meth:`~screenpy.actor.Actor.exit`.""" - return self.exit() - - def exit_through_vomitorium(self) -> None: - """Alias for :meth:`~screenpy.actor.Actor.exit`.""" - return self.exit() + exit_stage_left = exit_stage_right = exit_through_vomitorium = exit def __call__(self, *actions: Performable) -> None: - """Alias for :meth:`~screenpy.actor.Actor.attempts_to`.""" + """Alias for :meth:`attempts_to`.""" return self.attempts_to(*actions) def __repr__(self) -> str: diff --git a/tests/test_actions.py b/tests/test_actions.py index c3102441..f5fc5d68 100644 --- a/tests/test_actions.py +++ b/tests/test_actions.py @@ -362,9 +362,9 @@ def test_logs_the_value( class TestMakeNote: def test_can_be_instantiated(self) -> None: - mn1 = MakeNote(None) - mn2 = MakeNote.of(None) - mn3 = MakeNote.of_the(None).as_("") + mn1 = MakeNote(FakeQuestion()) + mn2 = MakeNote.of(FakeQuestion()) + mn3 = MakeNote.of_the(FakeQuestion()).as_("") assert isinstance(mn1, MakeNote) assert isinstance(mn2, MakeNote) @@ -393,7 +393,7 @@ def test_answers_question(self, Tester: Actor) -> None: def test_raises_without_key(self, Tester: Actor) -> None: with pytest.raises(UnableToAct): - MakeNote.of_the(None).perform_as(Tester) + MakeNote.of_the(FakeQuestion()).perform_as(Tester) def test_adds_note_to_director(self, Tester: Actor) -> None: key = "key"