Skip to content
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

docs: improve documentation for shares manager and model #358

Merged
merged 1 commit into from
Nov 9, 2024
Merged

docs: improve documentation for shares manager and model #358

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
41 changes: 22 additions & 19 deletions src/aioslsk/shares/manager.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ def _build_term_map(self, shared_directory: SharedDirectory):

async def get_shared_item(self, remote_path: str, username: Optional[str] = None) -> SharedItem:
"""Gets a shared item from the cache based on the given file path. If
the file does not exist in the `shared_items` or the file is present
the file does not exist in the ``shared_items`` or the file is present
in the cache but does not exist on disk a :class:`.FileNotFoundError` is
raised

Expand All @@ -313,10 +313,10 @@ async def get_shared_item(self, remote_path: str, username: Optional[str] = None

:param remote_path: the remote_path
:param username: optional username to check if the file is shared or not
:raise FileNotFoundError: filename was not found in shared_items or was found
but did not exist on disk
:raise FileNotFoundError: filename was not found in shared_items or was
found but did not exist on disk
:raise FileNotSharedError: file is found, but locked for the given
`username`
``username``
"""
for shared_directory in self._shared_directories:
try:
Expand All @@ -340,10 +340,14 @@ def add_shared_directory(
share_mode: DirectoryShareMode = DirectoryShareMode.EVERYONE,
users: Optional[list[str]] = None) -> SharedDirectory:
"""Adds a shared directory. This method will call :meth:`generate_alias`
and add the directory to the directory map. This method will not scan
the directory, for scanning see the :meth:`scan`,
:meth:`scan_directory_files` and :meth:`scan_directory_file_attributes`
methods.
and add the directory to the directory map.

This method will not scan the directory, however if the directory is a
(sub)child of an already registered shared directory the items from that
directory will be removed from the parent directory to the new directory

For scanning see the :meth:`scan`, :meth:`scan_directory_files` and
:meth:`scan_directory_file_attributes` methods.

:param shared_directory: path of the shared directory
:param share_mode: the share mode for the directory
Expand Down Expand Up @@ -384,7 +388,7 @@ def update_shared_directory(
self, directory: Union[str, SharedDirectory],
share_mode: Optional[DirectoryShareMode] = None,
users: Optional[list[str]] = None) -> SharedDirectory:
"""Updates `share_mode` and `users` values for the given directory
"""Updates ``share_mode`` and ``users`` values for the given directory

:param directory: if a string is given this method will attempt to find
the shared directory based on the absolute path
Expand Down Expand Up @@ -429,7 +433,7 @@ def remove_shared_directory(self, directory: Union[str, SharedDirectory]) -> Sha

And removes the `Music\\Artist_One\\ shared directory the files of that
directory get returned back to the parent directory. In this case file
`song_two.mp3` will be shared with EVERYONE again
``song_two.mp3`` will be shared with EVERYONE again

:param shared_directory: :class:`.SharedDirectory` instance to remove
:return: the removed directory
Expand Down Expand Up @@ -463,7 +467,8 @@ def get_shared_directory(self, directory: str) -> SharedDirectory:
"""Calculates the absolute path of given ``directory`` and looks for the
matching :class:`.SharedDirectory` instance

:raise SharedDirectoryError: if the directory is not found
:raise SharedDirectoryError: if there is no corresponding
:class:`.SharedDirectory` instance registered in this class
"""
abs_path = os.path.normpath(os.path.abspath(directory))
for shared_directory in self.shared_directories:
Expand Down Expand Up @@ -534,15 +539,14 @@ async def scan_directory_files(self, shared_directory: SharedDirectory):
self._cleanup_term_map()

async def scan_directory_file_attributes(self, shared_directory: SharedDirectory):
"""Scans the file attributes for files in the given `shared_directory`.
only files that do not yet have attributes will be scanned
"""Scans the file attributes for files in the given ``shared_directory``
only files that do not have attributes will be scanned

The results of the scan are handled internally and are automatically to
the :class:`.SharedItem` object for which the scan was performed

:param shared_directory: :class:`.SharedDirectory` instance for which
the files need to be scanned
:return: List of futures for each file that needs to be scanned
"""
loop = asyncio.get_running_loop()

Expand Down Expand Up @@ -573,11 +577,9 @@ async def scan_directory_file_attributes(self, shared_directory: SharedDirectory

def _extract_attributes_callback(self, item: SharedItem, future: asyncio.Future):
try:
attributes = future.result()
item.attributes = future.result()
except Exception:
logger.warning("exception fetching shared item attributes")
else:
item.attributes = attributes

async def scan(self):
"""Scan the files and their attributes for all directories currently
Expand Down Expand Up @@ -617,7 +619,7 @@ def query(
excluded_search_phrases: Optional[list[str]] = None) -> tuple[list[SharedItem], list[SharedItem]]:
"""Performs a query on the ``shared_directories`` returning the matching
items. If ``username`` is passed this method will return a list of
visible results and list of locked results. If `None` the second list
visible results and list of locked results. If ``None`` the second list
will always be empty.

This method makes a first pass using the built in term map and filters
Expand Down Expand Up @@ -877,7 +879,8 @@ def _get_child_directories(self, shared_directory: SharedDirectory):
return children

def is_directory_locked(self, directory: SharedDirectory, username: str) -> bool:
"""Checks if the shared directory is locked for the given ``username``"""
"""Checks if the shared directory is locked for the given ``username``
"""
if directory.share_mode == DirectoryShareMode.FRIENDS:
return username not in self._settings.users.friends
elif directory.share_mode == DirectoryShareMode.USERS:
Expand Down
Loading