sharepoint-v1-api 0.2.3__tar.gz → 0.2.4__tar.gz

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.2.4 – 2025-12-03
+
+### Added
+
+- New high‑level `SharePointSite` object providing lazy‑loaded site metadata
+
 ## 0.2.3 – 2025-12-02
 
 ### Added
@@ -22,7 +28,7 @@
 
 - `SharePointList.fields` property to retrieve list field definitions
 
-## 0.2.1 – 2025‑11‑06
+## 0.2.1 – 2025-11-06
 
 ### Added
 
@@ -34,7 +40,7 @@
 
 ### Changed
 
-- HTTP header handling unified; corrected `X‑HTTP‑Method: PUT` for full updates.
+- HTTP header handling unified; corrected `X-HTTP-Method: PUT` for full updates.
 - Error handling improved: generic `sys.exit(1)` replaced with explicit `TypeError`/`ConnectionError` exceptions.
 
 ### Fixed

{sharepoint_v1_api-0.2.3/sharepoint_v1_api.egg-info → sharepoint_v1_api-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sharepoint_v1_api
-Version: 0.2.3
+Version: 0.2.4
 Author: Aske Bluhme Klok
 License: MIT
 Keywords: Sharepoint
@@ -156,6 +156,12 @@ for v in versions:
 ```
 
 
+## 0.2.4 – 2025-12-03
+
+### Added
+
+- New high‑level `SharePointSite` object providing lazy‑loaded site metadata
+
 ## 0.2.3 – 2025-12-02
 
 ### Added
@@ -180,7 +186,7 @@ for v in versions:
 
 - `SharePointList.fields` property to retrieve list field definitions
 
-## 0.2.1 – 2025‑11‑06
+## 0.2.1 – 2025-11-06
 
 ### Added
 
@@ -192,7 +198,7 @@ for v in versions:
 
 ### Changed
 
-- HTTP header handling unified; corrected `X‑HTTP‑Method: PUT` for full updates.
+- HTTP header handling unified; corrected `X-HTTP-Method: PUT` for full updates.
 - Error handling improved: generic `sys.exit(1)` replaced with explicit `TypeError`/`ConnectionError` exceptions.
 
 ### Fixed

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4}/setup.py

@@ -1,6 +1,6 @@
 from setuptools import setup
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 
 with open("README.md", "r") as readme_file, open("CHANGELOG.md", "r") as changelog_file:
     long_description = f"{readme_file.read()}\n\n{changelog_file.read()}"

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4}/sharepoint_api/SharePointAPI.py

@@ -11,13 +11,14 @@ from .SharePointUserList import SharePointUserList
 from .SharePointListItem import SharePointListItem, SharepointSiteCase
 from .SharePointList import SharePointList, CasesList, TimeRegistrationList
 from .SharePointLists import SharePointLists
+from .SharePointSite import SharePointSite
 
 
 class SharePointAPI:
-    """High‑level client for interacting with SharePoint sites.
+    """High-level client for interacting with SharePoint sites.
 
     Provides methods for authentication, list management, file operations,
-    and time‑registration handling. All public interactions should be performed
+    and time-registration handling. All public interactions should be performed
     through an instance created via :meth:`_compact_init`.
     """
 
@@ -35,7 +36,7 @@ class SharePointAPI:
         Returns
         -------
         SharePointAPI
-            A fully‑initialised ``SharePointAPI`` object ready for use.
+            A fully-initialised ``SharePointAPI`` object ready for use.
 
         Notes
         -----
@@ -177,7 +178,7 @@ class SharePointAPI:
         Perform a POST request against the SharePoint REST API.
 
         Enhanced error handling:
-        * Network‑level errors (timeouts, DNS failures, etc.) are caught and re‑raised as
+        * Network-level errors (timeouts, DNS failures, etc.) are caught and re-raised as
           ``ConnectionError`` with a helpful message.
         * HTTP error codes are reported with status, URL and response body when available.
         * The method always returns a ``requests.Response`` on success (status 200, 201 or 204).
@@ -187,7 +188,7 @@ class SharePointAPI:
         url : str
             The full endpoint URL.
         post_data : dict
-            JSON‑serialisable payload to send.
+            JSON-serialisable payload to send.
         form_digest_value : str | None, optional
             FormDigest required for POST/PUT/MERGE operations.
         merge : bool, optional
@@ -238,7 +239,7 @@ class SharePointAPI:
         Perform a PUT request against the SharePoint REST API.
 
         Enhanced error handling:
-        * Network‑level errors (timeouts, DNS failures, etc.) are caught and re‑raised as
+        * Network-level errors (timeouts, DNS failures, etc.) are caught and re-raised as
           ``ConnectionError`` with a helpful message.
         * HTTP error codes are reported with status, URL and response body when available.
         * The method always returns a ``requests.Response`` on success (status 200, 201 or 204).
@@ -248,7 +249,7 @@ class SharePointAPI:
         url : str
             The full endpoint URL.
         put_data : dict
-            JSON‑serialisable payload to send.
+            JSON-serialisable payload to send.
         form_digest_value : str | None, optional
             FormDigest required for POST/PUT/MERGE operations.
         merge : bool, optional
@@ -295,10 +296,10 @@ class SharePointAPI:
     def _api_attachment_call(self, url: str, post_data: bytes | None = None, form_digest_value: str | None = None,
                              overwrite: bool = False, x_http_method: str | None = None) -> requests.Response:
         """
-        Perform an attachment‑related request (POST, PUT, DELETE) against the SharePoint REST API.
+        Perform an attachment-related request (POST, PUT, DELETE) against the SharePoint REST API.
 
         Enhanced error handling:
-        * Network‑level errors (timeouts, DNS failures, etc.) are caught and re‑raised as
+        * Network-level errors (timeouts, DNS failures, etc.) are caught and re-raised as
           ``ConnectionError`` with a helpful message.
         * HTTP error codes are reported with status, URL and response body when available.
         * The method always returns a ``requests.Response`` on success (status 200 or 204).
@@ -323,7 +324,7 @@ class SharePointAPI:
             'X-RequestDigest': f'{form_digest_value}'
         }
 
-        # Determine effective X‑HTTP‑Method
+        # Determine effective X-HTTP-Method
         if overwrite:
             headers['X-HTTP-Method'] = "PUT"
         if x_http_method:
@@ -337,7 +338,7 @@ class SharePointAPI:
                 raise ConnectionError(
                     f'Unsupported X-HTTP-Method: {x_http_method}')
 
-        # Add Content‑Length when payload present
+        # Add Content-Length when payload present
         if post_data is not None:
             headers['Content-Length'] = str(len(post_data))
 
@@ -365,7 +366,7 @@ class SharePointAPI:
         Perform a GET request against the SharePoint REST API.
 
         Enhanced error handling:
-        * Network‑level errors (timeouts, DNS failures, etc.) are caught and re‑raised as
+        * Network-level errors (timeouts, DNS failures, etc.) are caught and re-raised as
           ``ConnectionError`` with a helpful message.
         * HTTP error codes are reported with status, URL and response body when available.
         * The method always returns a ``requests.Response`` on success (status 200).
@@ -462,7 +463,7 @@ class SharePointAPI:
         Returns
         -------
         SharePointUserList
-            A list‑like container with :class:`SharePointUser` objects for each member.
+            A list-like container with :class:`SharePointUser` objects for each member.
         """
         # Build the request URL for the group's users.
         # SharePoint REST endpoint: /_api/web/sitegroups/GetByName('<group_name>')/users
@@ -503,7 +504,7 @@ class SharePointAPI:
             for user_settings in r.json()["d"]["results"]
         ]
 
-        # Return a ``SharePointUserList`` (consistent with other user‑retrieval methods).
+        # Return a ``SharePointUserList`` (consistent with other user-retrieval methods).
         return SharePointUserList(sharepoint_site, users)
 
     def get_user(self, sharepoint_site, user_id, select_fields=None):
@@ -554,6 +555,40 @@ class SharePointAPI:
 
         return SharePointLists(_lists)
 
+    def get_site_metadata(self, sharepoint_site: str) -> dict:
+        """
+        Retrieve metadata of a SharePoint site.
+
+        Parameters
+        ----------
+        sharepoint_site : str
+            Identifier of the SharePoint site (e.g., 'mySite').
+
+        Returns
+        -------
+        dict
+            Dictionary containing the site's metadata as returned by the SharePoint REST API.
+        """
+        r = self._api_get_call(
+            f'{self.sharepoint_url}/cases/{sharepoint_site}/_api/Web')
+        return r.json()["d"]
+
+    def get_site(self, sharepoint_site: str) -> SharePointSite:
+        """
+        Return a :class:`SharePointSite` object representing the given site.
+
+        Parameters
+        ----------
+        sharepoint_site : str
+            Identifier of the SharePoint site (e.g., ``'mySite'``).
+
+        Returns
+        -------
+        SharePointSite
+            A high-level wrapper around site-wide operations.
+        """
+        return SharePointSite(self, sharepoint_site)
+
     def get_list(self, sharepoint_site, sp_list, filters=None, top=1000, view_path=None, select_fields=None, SPListType: SharePointList = SharePointList) -> SharePointList:
         '''
             Returns a list from a given sharepoint_site using its guid

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4}/sharepoint_api/SharePointList.py

@@ -12,7 +12,7 @@ class SharePointList:
     Provides common functionality for handling list items, including
     retrieval, addition, and serialization to JSON. Subclasses such as
     :class:`CasesList` and :class:`TimeRegistrationList` extend this
-    class with domain‑specific behavior.
+    class with domain-specific behavior.
     """
 
     settings = None
@@ -194,7 +194,7 @@ class CasesList(SharePointList):
 
 class TimeRegistrationList(SharePointList):
     """
-    Specialized list for time‑registration entries.
+    Specialized list for time-registration entries.
 
     Inherits from :class:`SharePointList` and sets ``SPItem`` to the
     :class:`TimeRegistration` class.

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4}/sharepoint_api/SharePointListItem.py

@@ -8,8 +8,8 @@ class SharePointListItem:
 
     Provides access to common fields such as ``Id``, ``Title``, ``Created`` and
     ``Modified`` and handles lazy loading of related list data and version
-    history. Sub‑classes (e.g. :class:`SharepointSiteCase` or
-    :class:`TimeRegistration`) extend this base with domain‑specific properties.
+    history. Sub-classes (e.g. :class:`SharepointSiteCase` or
+    :class:`TimeRegistration`) extend this base with domain-specific properties.
     """
     ''' 
     '''

sharepoint_v1_api-0.2.4/sharepoint_api/SharePointSite.py

@@ -0,0 +1,188 @@
+"""
+Provides a high-level ``SharePointSite`` object that encapsulates site-wide
+metadata and offers convenience wrappers around common ``SharePointAPI``
+operations such as retrieving lists, users, and groups.
+"""
+
+from __future__ import annotations
+from datetime import datetime
+
+from typing import List, Optional
+import locale
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Imported only for type checking to avoid circular imports at runtime
+    from .SharePointAPI import SharePointAPI
+from .SharePointList import SharePointList
+from .SharePointLists import SharePointLists
+from .SharePointUser import SharePointUser
+from .SharePointUserList import SharePointUserList
+
+
+class SharePointSite:
+    """
+    High-level representation of a SharePoint site.
+
+    Parameters
+    ----------
+    api : SharePointAPI
+        The low-level client used for HTTP calls.
+    site_id : str
+        Identifier of the SharePoint site (e.g. ``"mySite"``).
+    """
+
+    def __init__(self, api: "SharePointAPI", site_id: str):
+        self._api = api
+        self.site_id = site_id
+        self._metadata: Optional[dict] = None
+
+    # -----------------------------------------------------------------
+    # Internal helpers
+    # -----------------------------------------------------------------
+    def _ensure_metadata(self) -> dict:
+        """Fetch site metadata on first use and cache it."""
+        if self._metadata is None:
+            self._metadata = self._api.get_site_metadata(self.site_id)
+        return self._metadata
+
+    # -----------------------------------------------------------------
+    # Exposed properties (lazy-loaded)
+    # -----------------------------------------------------------------
+    @property
+    def title(self) -> str:
+        """Site title."""
+        return self._ensure_metadata().get("Title", "")
+
+    @property
+    def url(self) -> str:
+        """Absolute URL of the site."""
+        return self._ensure_metadata().get("Url", "")
+
+    @property
+    def description(self) -> str:
+        """Site description, if present."""
+        return self._ensure_metadata().get("Description", "")
+
+    @property
+    def created(self) -> datetime | None:
+        """
+        Creation date of the SharePoint site.
+
+        Returns a ``datetime`` object parsed from the ``Created`` metadata
+        field, or ``None`` if the field is missing or cannot be parsed.
+        """
+        created_str = self._ensure_metadata().get("Created")
+        if not created_str:
+            return None
+        try:
+            # ``fromisoformat`` handles the ISO‑8601 format returned by SharePoint.
+            return datetime.fromisoformat(created_str)
+        except ValueError:
+            # Fallback: return None if parsing fails.
+            return None
+
+    @property
+    def language_id(self) -> int:
+        """Raw LCID value returned by SharePoint."""
+        return self._ensure_metadata().get("Language", 0)
+
+    @property
+    def language_name(self) -> str:
+        """
+        Human-readable language name derived from the LCID using the
+        ``locale`` module. If the LCID is unknown or the locale cannot be set,
+        a fallback string is returned.
+        """
+        lcid = self.language_id
+        locale_code = locale.windows_locale.get(lcid)
+        if not locale_code:
+            return f"Unknown (LCID={lcid})"
+        try:
+            # Attempt to set the locale; may fail if not installed.
+            locale.setlocale(locale.LC_ALL, locale_code)
+            # locale.getlocale() returns a tuple like ('en_US', 'UTF-8')
+            loc = locale.getlocale()[0]
+            if loc:
+                # Return the locale identifier (e.g., 'en_US')
+                return loc
+        except locale.Error:
+            # Locale not available on the system; fall back to the code.
+            pass
+        # Fallback to the raw locale code string.
+        return locale_code
+
+    # -----------------------------------------------------------------
+    # Convenience wrappers around ``SharePointAPI`` methods
+    # -----------------------------------------------------------------
+    def get_lists(self) -> SharePointLists:
+        """Return a ``SharePointLists`` collection for this site."""
+        return self._api.get_lists(self.site_id)
+
+    def get_users(
+        self,
+        filters: Optional[str] = None,
+        select_fields: Optional[List[str]] = None,
+    ) -> SharePointUserList:
+        """Retrieve users from the site."""
+        return self._api.get_users(self.site_id, filters=filters, select_fields=select_fields)
+
+    def get_group_users(
+        self,
+        group_name: str,
+        filters: Optional[str] = None,
+        select_fields: Optional[List[str]] = None,
+    ) -> SharePointUserList:
+        """Retrieve members of a SharePoint group."""
+        return self._api.get_group_users(
+            self.site_id, group_name, filters=filters, select_fields=select_fields
+        )
+
+    def get_user(
+        self,
+        user_id: int,
+        select_fields: Optional[List[str]] = None,
+    ) -> SharePointUser:
+        """Retrieve a single user by ID."""
+        return self._api.get_user(self.site_id, user_id, select_fields=select_fields)
+
+    def get_list(
+        self,
+        sp_list,
+        filters=None,
+        top: int = 1000,
+        view_path=None,
+        select_fields=None,
+        SPListType: SharePointList = SharePointList,
+    ) -> SharePointList:
+        """Delegate to ``SharePointAPI.get_list`` for this site."""
+        return self._api.get_list(
+            self.site_id,
+            sp_list,
+            filters,
+            top,
+            view_path,
+            select_fields,
+            SPListType=SPListType,
+        )
+
+    def get_list_by_name(
+        self,
+        sp_list_name: str,
+        filters=None,
+        top: int = 1000,
+        view_path=None,
+        select_fields=None,
+        SPListType: SharePointList = SharePointList,
+    ) -> SharePointList:
+        """Delegate to ``SharePointAPI.get_list_by_name`` for this site."""
+        return self._api.get_list_by_name(
+            self.site_id,
+            sp_list_name,
+            filters,
+            top,
+            view_path,
+            select_fields,
+            SPListType=SPListType,
+        )

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4}/sharepoint_api/SharePointTimeRegistration.py

@@ -6,7 +6,7 @@ from sharepoint_api.SharePointListItem import SharePointListItem
 
 class TimeRegistration(SharePointListItem):
     """
-    Represents a time‑registration entry associated with a SharePoint list item.
+    Represents a time-registration entry associated with a SharePoint list item.
 
     Extends :class:`SharePointListItem` with fields specific to time tracking,
     such as ``Hours``, ``DoneBy`` and related timestamps. Provides lazy loading of the

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4}/sharepoint_api/__init__.py

@@ -1,6 +1,6 @@
 """sharepoint_api package
 
-Provides a high‑level Python client for interacting with SharePoint sites via the
+Provides a high-level Python client for interacting with SharePoint sites via the
 `SharePointAPI` class. The package includes helpers for working with lists,
 list items, users, and time registrations.
 
@@ -18,4 +18,5 @@ api = SharePointAPI._compact_init(creds)
 ```
 """
 
-from .SharePointAPI import SharePointAPI
+from .SharePointAPI import SharePointAPI
+from .SharePointSite import SharePointSite

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4/sharepoint_v1_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sharepoint_v1_api
-Version: 0.2.3
+Version: 0.2.4
 Author: Aske Bluhme Klok
 License: MIT
 Keywords: Sharepoint
@@ -156,6 +156,12 @@ for v in versions:
 ```
 
 
+## 0.2.4 – 2025-12-03
+
+### Added
+
+- New high‑level `SharePointSite` object providing lazy‑loaded site metadata
+
 ## 0.2.3 – 2025-12-02
 
 ### Added
@@ -180,7 +186,7 @@ for v in versions:
 
 - `SharePointList.fields` property to retrieve list field definitions
 
-## 0.2.1 – 2025‑11‑06
+## 0.2.1 – 2025-11-06
 
 ### Added
 
@@ -192,7 +198,7 @@ for v in versions:
 
 ### Changed
 
-- HTTP header handling unified; corrected `X‑HTTP‑Method: PUT` for full updates.
+- HTTP header handling unified; corrected `X-HTTP-Method: PUT` for full updates.
 - Error handling improved: generic `sys.exit(1)` replaced with explicit `TypeError`/`ConnectionError` exceptions.
 
 ### Fixed

{sharepoint_v1_api-0.2.3 → sharepoint_v1_api-0.2.4}/sharepoint_v1_api.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ sharepoint_api/SharePointAPI.py
 sharepoint_api/SharePointList.py
 sharepoint_api/SharePointListItem.py
 sharepoint_api/SharePointLists.py
+sharepoint_api/SharePointSite.py
 sharepoint_api/SharePointTimeRegistration.py
 sharepoint_api/SharePointUser.py
 sharepoint_api/SharePointUserList.py