allow 3.8+

.github/workflows/build.yaml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.x"]
+        python-version: ["3.8", "3.x"]
 
     name: "Build @ ${{ matrix.python-version }}"
     steps:

.github/workflows/coverage_and_lint.yaml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ '3.11' ]
+        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.x' ]
 
     name: "Type Coverage and Linting @ ${{ matrix.python-version }}"
     steps:

.gitignore

@@ -1,9 +1,5 @@
 .vscode/
-__ignore__/
-__pycache__/
-*.pyc
-/dist/
-/*.egg-info/
+*.py[cod]
+.venv/
+.idea/
 docs/build
-docs/_static/
-*.ipynb

README.md

@@ -43,7 +43,6 @@ python -m pip install git+https://github.com/PythonistaGuild/mystbin.py.git
 ```
 
 ### Usage examples
-Since the project is considered multi-sync, it will work in a sync/async environment, see the optional dependency of `requests` below.
 
 ```py
 # async example - it will default to async
@@ -52,6 +51,8 @@ import mystbin
 client = mystbin.Client()
 
 paste = await client.create_paste(filename="Hello.txt", content="Hello there!")
+# we also support passing a mystbin.File directly to the `file=` kwarg!
+
 str(paste)
 >>> 'https://mystb.in/<your generated ID>'
 
@@ -70,7 +71,7 @@ import mystbin
 file = mystbin.File(filename="File1.txt", content="Hello there!")
 file2 = mystbin.File(filename="test.py", content="print('hello!')")
 
-paste = await client.create_multifile_paste(files=[file, file2])
+paste = await client.create_paste(files=[file, file2])
 
 for file in paste.files:
     print(file.content)

docs/conf.py

@@ -13,6 +13,7 @@
 import os
 import re
 import sys
+from typing import Dict, List, Tuple
 
 
 # from typing import Literal, Optional
@@ -65,7 +66,7 @@
 sys.path.insert(0, os.path.abspath(".."))
 sys.path.append(os.path.abspath("extensions"))
 
-extensions: list[str] = [
+extensions: List[str] = [
     "sphinx.ext.autodoc",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
@@ -74,10 +75,10 @@
     "sphinxcontrib_trio",
 ]
 
-extlinks: dict[str, tuple[str, str]] = {"issue": (f"{_GITHUB}/issues/%s", "GH-%s")}
+extlinks: Dict[str, Tuple[str, str]] = {"issue": (f"{_GITHUB}/issues/%s", "GH-%s")}
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path: list[str] = ["_templates"]
+templates_path: List[str] = ["_templates"]
 
 autodoc_typehints: str = "both"
 autodoc_typehints_format: str = "short"
@@ -90,10 +91,10 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns: list[str] = ["build", "Thumbs.db", ".DS_Store"]
+exclude_patterns: List[str] = ["build", "Thumbs.db", ".DS_Store"]
 
 # Links used for cross-referencing other documentation
-intersphinx_mapping: dict[str, tuple[str, None]] = {
+intersphinx_mapping: Dict[str, Tuple[str, None]] = {
     "python": ("https://docs.python.org/3", None),
     "aiohttp": ("https://docs.aiohttp.org/en/stable/", None),
     "requests": ("https://requests.readthedocs.io/en/latest/", None),
@@ -113,15 +114,15 @@
 # a list of builtin themes.
 #
 html_theme: str = "furo"
-html_theme_options: dict[str, list[dict[str, str]]] = {
+html_theme_options: Dict[str, List[Dict[str, str]]] = {
     "footer_icons": [
         {"name": "Discord", "url": _DISCORD, "html": _DISCORD_SVG, "class": ""},
         {"name": "Github", "url": _GITHUB, "html": _GITHUB_SVG, "class": ""},
         {"name": "readthedocs.io", "url": _RTD, "html": _RTD_SVG, "class": ""},
     ],
 }
 
-resource_links: dict[str, str] = {
+resource_links: Dict[str, str] = {
     "github": _GITHUB,
     "issues": f"{_GITHUB}/issues",
     "discussions": f"{_GITHUB}/discussions",

mystbin/client.py

@@ -23,7 +23,7 @@
 from __future__ import annotations
 
 import datetime
-from typing import Optional
+from typing import List, Optional, Sequence, overload
 
 import aiohttp
 
@@ -48,11 +48,52 @@ async def close(self) -> None:
         """
         await self.http.close()
 
+    @overload
     async def create_paste(
         self,
         *,
         filename: str,
         content: str,
+        file: None = ...,
+        files: None = ...,
+        password: Optional[str] = ...,
+        expires: Optional[datetime.datetime] = ...,
+    ) -> Paste:
+        ...
+
+    @overload
+    async def create_paste(
+        self,
+        *,
+        filename: None = ...,
+        content: None = ...,
+        file: File,
+        files: None = ...,
+        password: Optional[str] = ...,
+        expires: Optional[datetime.datetime] = ...,
+    ) -> Paste:
+        ...
+
+    @overload
+    async def create_paste(
+        self,
+        *,
+        filename: None = ...,
+        content: None = ...,
+        file: None = ...,
+        files: Sequence[File],
+        password: Optional[str] = ...,
+        expires: Optional[datetime.datetime] = ...,
+    ) -> Paste:
+        ...
+
+    async def create_paste(
+        self,
+        *,
+        filename: Optional[str] = None,
+        content: Optional[str] = None,
+        file: Optional[File] = None,
+        files: Optional[Sequence[File]] = None,
         password: Optional[str] = None,
         expires: Optional[datetime.datetime] = None,
     ) -> Paste:
@@ -62,46 +103,49 @@ async def create_paste(
 
         Parameters
         -----------
-        filename: :class:`str`
+        filename: Optional[:class:`str`]
             The filename to create.
-        content: :class:`str`
+        content: Optional[:class:`str`]
             The content of the file you are creating.
+        file: Optional[:class:`~mystbin.File`]
+            The pre-created file you wish to upload.
+        files: Optional[List[:class:`~mystbin.File`]]
+            The pre-creates list of files you wish to upload.
         password: Optional[:class:`str`]
             The password of the paste, if any.
         expires: Optional[:class:`datetime.datetime`]
             When the paste expires, if any.
 
+        Raises
+        -------
+        :exc:`ValueError`
+            A bad combinarion of singular and plural pastes were passed.
+
         Returns
         --------
         :class:`mystbin.Paste`
             The paste that was created.
+
+
+        ..note::
+            Passing combinations of both singular and plural files is not supports and will raise an exception.
+            Internally the order of precesence is ``files`` > ``file`` > ``filename and content``.
         """
-        file = File(filename=filename, content=content)
-        data = await self.http.create_paste(file=file, password=password, expires=expires)
-        return Paste.from_data(data)
+        if (filename and content) and file:
+            raise ValueError("Cannot provide both `file` and `filename`/`content`")
 
-    async def create_multifile_paste(
-        self, *, files: list[File], password: Optional[str] = None, expires: Optional[datetime.datetime] = None
-    ) -> Paste:
-        """|coro|
+        resolved_files: Sequence[File] = []
+        if filename and content:
+            resolved_files = [File(filename=filename, content=content)]
+        elif file:
+            resolved_files = [file]
 
-        Create a paste with multiple files on mystb.in.
+        if resolved_files and files:
+            raise ValueError("Cannot provide both singular and plural files.")
 
-        Parameters
-        ------------
-        files: list[:class:`mystbin.File`]
-            A list of files to create on mystbin.
-        password: Optional[:class:`str`]
-            The password for this paste, if any.
-        expires: Optional[:class:`datetime.datetime`]
-            When this paste expires, if any.
+        resolved_files = files or resolved_files
 
-        Returns
-        --------
-        :class:`mystbin.Paste`
-            The paste that was created.
-        """
-        data = await self.http.create_paste(files=files, password=password, expires=expires)
+        data = await self.http.create_paste(files=resolved_files, password=password, expires=expires)
         return Paste.from_data(data)
 
     @require_authentication
@@ -118,14 +162,14 @@ async def delete_paste(self, paste_id: str, /) -> None:
         await self.http.delete_pastes(paste_ids=[paste_id])
 
     @require_authentication
-    async def delete_pastes(self, paste_ids: list[str], /) -> None:
+    async def delete_pastes(self, paste_ids: List[str], /) -> None:
         """|coro|
 
         Delete multiple pastes.
 
         Parameters
         -----------
-        paste_ids: list[:class:`str`]
+        paste_ids: List[:class:`str`]
             The pastes to delete.
         """
         await self.http.delete_pastes(paste_ids=paste_ids)
@@ -145,55 +189,8 @@ async def get_paste(self, paste_id: str, *, password: Optional[str] = None) -> P
         data = await self.http.get_paste(paste_id=paste_id, password=password)
         return Paste.from_data(data)
 
-    # @overload
-    # async def edit_paste(self, paste_id: str, *, new_content: str, new_filename: ..., new_expires: ...) -> None:
-    #     ...
-
-    # @overload
-    # async def edit_paste(self, paste_id: str, *, new_content: ..., new_filename: str, new_expires: ...) -> None:
-    #     ...
-
-    # @overload
-    # async def edit_paste(
-    #     self, paste_id: str, *, new_content: ..., new_filename: ..., new_expires: datetime.datetime
-    # ) -> None:
-    #     ...
-
-    # @overload
-    # async def edit_paste(self, paste_id: str, *, new_content: str, new_filename: str, new_expires: ...) -> None:
-    #     ...
-
-    # @overload
-    # async def edit_paste(
-    #     self, paste_id: str, *, new_content: str, new_filename: ..., new_expires: datetime.datetime
-    # ) -> None:
-    #     ...
-
-    # @overload
-    # async def edit_paste(
-    #     self, paste_id: str, *, new_content: ..., new_filename: str, new_expires: datetime.datetime
-    # ) -> None:
-    #     ...
-
-    # @overload
-    # async def edit_paste(
-    #     self, paste_id: str, *, new_content: str, new_filename: str, new_expires: datetime.datetime
-    # ) -> None:
-    #     ...
-
-    # @require_authentication
-    # async def edit_paste(
-    #     self,
-    #     paste_id: str,
-    #     *,
-    #     new_content: Optional[str] = MISSING,
-    #     new_filename: Optional[str] = MISSING,
-    #     new_expires: Optional[datetime.datetime] = MISSING,
-    # ) -> None:
-    #     await self.http._edit_paste(paste_id, new_content=new_content, new_filename=new_filename, new_expires=new_expires)
-
     @require_authentication
-    async def get_user_pastes(self, *, limit: int = 100) -> list[Paste]:
+    async def get_user_pastes(self, *, limit: int = 100) -> List[Paste]:
         """|coro|
 
         Get all pastes belonging to the current authenticated user.
@@ -205,7 +202,7 @@ async def get_user_pastes(self, *, limit: int = 100) -> list[Paste]:
 
         Returns
         --------
-        list[:class:`Paste`]
+        List[:class:`Paste`]
             The pastes that were fetched.
         """
         data = await self.http.get_my_pastes(limit=limit)