Skip to content

Short-form to fully qualified object naming #381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
phecke wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Short-form to fully qualified object naming #381

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions libraries/microsoft-agents-activity/microsoft_agents/activity/activity.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,7 +437,7 @@ def as_typing_activity(self):
@staticmethod
def create_contact_relation_update_activity():
"""
Creates an instance of the :class:`Activity` class as a ContactRelationUpdateActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as a ContactRelationUpdateActivity object.

:returns: The new contact relation update activity.
"""
Expand All @@ -446,7 +446,7 @@ def create_contact_relation_update_activity():
@staticmethod
def create_conversation_update_activity():
"""
Creates an instance of the :class:`Activity` class as a ConversationUpdateActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as a ConversationUpdateActivity object.

:returns: The new conversation update activity.
"""
Expand All @@ -455,7 +455,7 @@ def create_conversation_update_activity():
@staticmethod
def create_end_of_conversation_activity():
"""
Creates an instance of the :class:`Activity` class as an EndOfConversationActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as an EndOfConversationActivity object.

:returns: The new end of conversation activity.
"""
Expand All @@ -464,7 +464,7 @@ def create_end_of_conversation_activity():
@staticmethod
def create_event_activity():
"""
Creates an instance of the :class:`Activity` class as an EventActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as an EventActivity object.

:returns: The new event activity.
"""
Expand All @@ -473,7 +473,7 @@ def create_event_activity():
@staticmethod
def create_handoff_activity():
"""
Creates an instance of the :class:`Activity` class as a HandoffActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as a HandoffActivity object.

:returns: The new handoff activity.
"""
Expand All @@ -482,7 +482,7 @@ def create_handoff_activity():
@staticmethod
def create_invoke_activity():
"""
Creates an instance of the :class:`Activity` class as an InvokeActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as an InvokeActivity object.

:returns: The new invoke activity.
"""
Expand All @@ -491,7 +491,7 @@ def create_invoke_activity():
@staticmethod
def create_message_activity():
"""
Creates an instance of the :class:`Activity` class as a MessageActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as a MessageActivity object.

:returns: The new message activity.
"""
Expand Down Expand Up @@ -588,7 +588,7 @@ def create_trace_activity(
name: str, value: object = None, value_type: str = None, label: str = None
):
"""
Creates an instance of the :class:`Activity` class as a TraceActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as a TraceActivity object.

:param name: The name of the trace operation to create.
:param value: Optional, the content for this trace operation.
Expand All @@ -612,7 +612,7 @@ def create_trace_activity(
@staticmethod
def create_typing_activity() -> "Activity":
"""
Creates an instance of the :class:`Activity` class as a TypingActivity object.
Creates an instance of the :class:`microsoft_agents.activity.Activity` class as a TypingActivity object.

:returns: The new typing activity.
"""
Expand Down Expand Up @@ -655,7 +655,7 @@ def get_mentions(self) -> list[Mention]:
:returns: The array of mentions; or an empty array, if none are found.

.. remarks::
This method is defined on the :class:`Activity` class, but is only intended for use with a message activity,
This method is defined on the :class:`microsoft_agents.activity.Activity` class, but is only intended for use with a message activity,
where the activity Activity.Type is set to ActivityTypes.Message.
"""
if not self.entities:
Expand Down Expand Up @@ -683,7 +683,7 @@ def has_content(self) -> bool:
:returns: True, if this activity has any content to send; otherwise, false.

.. remarks::
This method is defined on the :class:`Activity` class, but is only intended for use with a message activity,
This method is defined on the :class:`microsoft_agents.activity.Activity` class, but is only intended for use with a message activity,
where the activity Activity.Type is set to ActivityTypes.Message.
"""
if self.text and self.text.strip():
Expand Down
44 changes: 22 additions & 22 deletions libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/activity_handler.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ async def on_turn(
process, which allows a derived class to provide type-specific logic in a controlled way.
In a derived class, override this method to add logic that applies to all activity types.
Also
- Add logic to apply before the type-specific logic and before calling :meth:`on_turn()`.
- Add logic to apply after the type-specific logic after calling :meth:`on_turn()`.
- Add logic to apply before the type-specific logic and before calling :meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn`.
- Add logic to apply after the type-specific logic after calling :meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn`.
"""
if turn_context is None:
raise TypeError("ActivityHandler.on_turn(): turn_context cannot be None.")
Expand Down Expand Up @@ -145,21 +145,21 @@ async def on_message_delete_activity( # pylint: disable=unused-argument
async def on_conversation_update_activity(self, turn_context: TurnContextProtocol):
"""
Invoked when a conversation update activity is received from the channel when the base behavior of
:meth:`on_turn()` is used.
:meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn` is used.

:param turn_context: The context object for this turn
:type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
:returns: A task that represents the work queued to execute
:rtype: Awaitable[None]

.. note::
When the :meth:`on_turn()` method receives a conversation update activity, it calls this
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn` method receives a conversation update activity, it calls this
method.
Also
- If the conversation update activity indicates that members other than the agent joined the conversation,
it calls the :meth:`on_members_added_activity()` method.
it calls the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_members_added_activity` method.
- If the conversation update activity indicates that members other than the agent left the conversation,
it calls the :meth:`on_members_removed_activity()` method.
it calls the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_members_removed_activity` method.
- In a derived class, override this method to add logic that applies to all conversation update activities.
Add logic to apply before the member added or removed logic before the call to this base class method.
"""
Expand Down Expand Up @@ -189,7 +189,7 @@ async def on_members_added_activity(
:rtype: Awaitable[None]

.. note::
When the :meth:`on_conversation_update_activity()` method receives a conversation
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_conversation_update_activity` method receives a conversation
update activity that indicates
one or more users other than the agent are joining the conversation, it calls this method.
"""
Expand All @@ -211,7 +211,7 @@ async def on_members_removed_activity(
:rtype: Awaitable[None]

.. note::
When the :meth:`on_conversation_update_activity()` method receives a conversation
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_conversation_update_activity` method receives a conversation
update activity that indicates one or more users other than the agent are leaving the conversation,
it calls this method.
"""
Expand All @@ -221,7 +221,7 @@ async def on_members_removed_activity(
async def on_message_reaction_activity(self, turn_context: TurnContextProtocol):
"""
Invoked when an event activity is received from the connector when the base behavior of
:meth:`on_turn()` is used.
:meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn` is used.

:param turn_context: The context object for this turn
:type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
Expand All @@ -236,13 +236,13 @@ async def on_message_reaction_activity(self, turn_context: TurnContextProtocol):
Message reactions are only supported by a few channels. The activity that the message reaction corresponds
to is indicated in the reply to Id property. The value of this property is the activity id of a previously
sent activity given back to the agent as the response from a send call.
When the :meth:`on_turn()` method receives a message reaction activity, it calls this
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn` method receives a message reaction activity, it calls this
method.

- If the message reaction indicates that reactions were added to a message, it calls
:meth:`on_reactions_added()`.
:meth:`microsoft_agents.hosting.core.ActivityHandler.on_reactions_added`.
- If the message reaction indicates that reactions were removed from a message, it calls
:meth:`on_reactions_removed()`.
:meth:`microsoft_agents.hosting.core.ActivityHandler.on_reactions_removed`.

In a derived class, override this method to add logic that applies to all message reaction activities.
Add logic to apply before the reactions added or removed logic before the call to the this base class
Expand Down Expand Up @@ -314,17 +314,17 @@ async def on_reactions_removed( # pylint: disable=unused-argument
async def on_event_activity(self, turn_context: TurnContextProtocol):
"""
Invoked when an event activity is received from the connector when the base behavior of
:meth:`on_turn()` is used.
:meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn` is used.

:param turn_context: The context object for this turn
:type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
:returns: A task that represents the work queued to execute
:rtype: Awaitable[None]

.. note::
When the :meth:`on_turn()` method receives an event activity, it calls this method.
If the activity name is `tokens/response`, it calls :meth:`on_token_response_event()`;
otherwise, it calls :meth:`on_event()`.
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn` method receives an event activity, it calls this method.
If the activity name is `tokens/response`, it calls :meth:`microsoft_agents.hosting.core.ActivityHandler.on_token_response_event`;
otherwise, it calls :meth:`microsoft_agents.hosting.core.ActivityHandler.on_event`.

In a derived class, override this method to add logic that applies to all event activities.
Add logic to apply before the specific event-handling logic before the call to this base class method.
Expand All @@ -344,7 +344,7 @@ async def on_token_response_event( # pylint: disable=unused-argument
):
"""
Invoked when a `tokens/response` event is received when the base behavior of
:meth:`on_event_activity()` is used.
:meth:`microsoft_agents.hosting.core.ActivityHandler.on_event_activity` is used.
If using an `oauth_prompt`, override this method to forward this activity to the current dialog.

:param turn_context: The context object for this turn
Expand All @@ -353,7 +353,7 @@ async def on_token_response_event( # pylint: disable=unused-argument
:rtype: Awaitable[None]

.. note::
When the :meth:`on_event()` method receives an event with an activity name of
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_event` method receives an event with an activity name of
`tokens/response`, it calls this method. If your agent uses an `oauth_prompt`, forward the incoming
activity to the current dialog.
"""
Expand All @@ -364,15 +364,15 @@ async def on_event( # pylint: disable=unused-argument
):
"""
Invoked when an event other than `tokens/response` is received when the base behavior of
:meth:`on_event_activity()` is used.
:meth:`microsoft_agents.hosting.core.ActivityHandler.on_event_activity` is used.

:param turn_context: The context object for this turn
:type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
:returns: A task that represents the work queued to execute
:rtype: Awaitable[None]

.. note::
When the :meth:`on_event_activity()` is used method receives an event with an
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_event_activity` is used method receives an event with an
activity name other than `tokens/response`, it calls this method.
Comment on lines +375 to 376
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar issue in the note: "When the ... is used method receives..." reads incorrectly and is likely missing the word "method" after the reference (and/or a comma). Adjust the sentence so it parses clearly in the generated reference docs.

Suggested change
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_event_activity` is used method receives an event with an
activity name other than `tokens/response`, it calls this method.
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_event_activity` method is used, it receives an event with an
activity name other than `tokens/response` and calls this method.

Copilot uses AI. Check for mistakes.
This method could optionally be overridden if the agent is meant to handle miscellaneous events.
"""
Expand Down Expand Up @@ -456,7 +456,7 @@ async def on_unrecognized_activity_type( # pylint: disable=unused-argument
):
"""
Invoked when an activity other than a message, conversation update, or event is received when the base
behavior of :meth:`on_turn()` is used.
behavior of :meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn` is used.
If overridden, this method could potentially respond to any of the other activity types.

:param turn_context: The context object for this turn
Expand All @@ -465,7 +465,7 @@ async def on_unrecognized_activity_type( # pylint: disable=unused-argument
:rtype: Awaitable[None]

.. note::
When the :meth:`on_turn()` method receives an activity that is not a message,
When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_turn` method receives an activity that is not a message,
conversation update, message reaction, or event activity, it calls this method.
"""
return
Expand Down
12 changes: 6 additions & 6 deletions ...ries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/agent_application.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -308,7 +308,7 @@ async def on_event(context: TurnContext, state: TurnState):
:type activity_type: Union[str, microsoft_agents.activity.ActivityTypes, list[Union[str, microsoft_agents.activity.ActivityTypes]]]
:param auth_handlers: Optional list of authorization handler IDs for the route.
:type auth_handlers: Optional[list[str]]
:param kwargs: Additional route configuration passed to :meth:`add_route`.
:param kwargs: Additional route configuration passed to :meth:`microsoft_agents.hosting.core.AgentApplication.add_route`.
"""

def __selector(context: TurnContext):
Expand Down Expand Up @@ -345,7 +345,7 @@ async def on_hi_message(context: TurnContext, state: TurnState):
:type select: Union[str, Pattern[str], list[Union[str, Pattern[str]]]]
:param auth_handlers: Optional list of authorization handler IDs for the route.
:type auth_handlers: Optional[list[str]]
:param kwargs: Additional route configuration passed to :meth:`add_route`.
:param kwargs: Additional route configuration passed to :meth:`microsoft_agents.hosting.core.AgentApplication.add_route`.
"""

def __selector(context: TurnContext):
Expand Down Expand Up @@ -390,7 +390,7 @@ async def on_channel_created(context: TurnContext, state: TurnState):
:type type: microsoft_agents.activity.ConversationUpdateTypes
:param auth_handlers: Optional list of authorization handler IDs for the route.
:type auth_handlers: Optional[list[str]]
:param kwargs: Additional route configuration passed to :meth:`add_route`.
:param kwargs: Additional route configuration passed to :meth:`microsoft_agents.hosting.core.AgentApplication.add_route`.
"""

def __selector(context: TurnContext):
Expand Down Expand Up @@ -444,7 +444,7 @@ async def on_reactions_added(context: TurnContext, state: TurnState):
:type type: microsoft_agents.activity.MessageReactionTypes
:param auth_handlers: Optional list of authorization handler IDs for the route.
:type auth_handlers: Optional[list[str]]
:param kwargs: Additional route configuration passed to :meth:`add_route`.
:param kwargs: Additional route configuration passed to :meth:`microsoft_agents.hosting.core.AgentApplication.add_route`.
"""

def __selector(context: TurnContext):
Expand Down Expand Up @@ -494,7 +494,7 @@ async def on_edit_message(context: TurnContext, state: TurnState):
:type type: microsoft_agents.activity.MessageUpdateTypes
:param auth_handlers: Optional list of authorization handler IDs for the route.
:type auth_handlers: Optional[list[str]]
:param kwargs: Additional route configuration passed to :meth:`add_route`.
:param kwargs: Additional route configuration passed to :meth:`microsoft_agents.hosting.core.AgentApplication.add_route`.
"""

def __selector(context: TurnContext):
Expand Down Expand Up @@ -553,7 +553,7 @@ async def on_handoff(context: TurnContext, state: TurnState, continuation: str):

:param auth_handlers: Optional list of authorization handler IDs for the route.
:type auth_handlers: Optional[list[str]]
:param kwargs: Additional route configuration passed to :meth:`add_route`.
:param kwargs: Additional route configuration passed to :meth:`microsoft_agents.hosting.core.AgentApplication.add_route`.
"""

def __selector(context: TurnContext) -> bool:
Expand Down
2 changes: 1 addition & 1 deletion libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/app_options.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,6 @@ class ApplicationOptions:
proactive: Optional[ProactiveOptions] = None
"""
Optional. Options for the proactive messaging subsystem.
When set, :attr:`AgentApplication.proactive` is available for storing
When set, :attr:`microsoft_agents.hosting.core.AgentApplication.proactive` is available for storing
conversations and initiating proactive turns.
"""
4 changes: 2 additions & 2 deletions libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/input_file.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ class InputFileDownloader(ABC):
Abstract base class for a plugin responsible for downloading files provided by the user.

Implementations should download any files referenced by the incoming activity and return a
list of :class:`InputFile` instances representing the downloaded content.
list of :class:`microsoft_agents.hosting.core.InputFile` instances representing the downloaded content.
"""
Comment on lines 36 to 38
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docstring references microsoft_agents.hosting.core.InputFile, but the class is defined in this module and the :rtype: below already uses microsoft_agents.hosting.core.app.input_file.InputFile. Align these to a single fully qualified path (preferably the defining module path) to avoid broken/duplicate API reference entries.

Copilot uses AI. Check for mistakes.

@abstractmethod
Expand All @@ -44,6 +44,6 @@ async def download_files(self, context: TurnContext) -> List[InputFile]:

:param context: The turn context for the current request.
:type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
:return: A list of downloaded :class:`InputFile` objects.
:return: A list of downloaded :class:`microsoft_agents.hosting.core.InputFile` objects.
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The :return: type uses microsoft_agents.hosting.core.InputFile while :rtype: uses microsoft_agents.hosting.core.app.input_file.InputFile. Use the same fully qualified type in both fields so documentation tooling resolves the return type consistently.

Suggested change
:return: A list of downloaded :class:`microsoft_agents.hosting.core.InputFile` objects.
:return: A list of downloaded :class:`microsoft_agents.hosting.core.app.input_file.InputFile` objects.

Copilot uses AI. Check for mistakes.
:rtype: list[:class:`microsoft_agents.hosting.core.app.input_file.InputFile`]
"""
Loading
Loading