feat(docs): update documentation with configure_splat usage

Author: uptickmetachu

.gitignore

@@ -1,3 +1,4 @@
+dist/
 invoke.json
 splat/prince
 splat/fonts/*
@@ -14,4 +15,4 @@ fonts.zip
 # Prince licence file
 license.dat
 # Layer working directory
-python/
+python/

README.md

@@ -1,29 +1,60 @@
 # splat
+
 splat is simple aws lambda function that takes HTML/CSS/JS, invokes PrinceXML to render it and returns the resulting PDF in one of many ways.
 
 It is intended to be a DIY docraptor of sorts.
 
 ## Installation
+
 Simply build the docker image, deploy it to AWS, then invoke the lambda with an event body JSON that performs the desired operation. For example: `{"document_content": "<h1>Hello, World!</h1>"}`
 
 ## Ways of invoking splat
+
 ### Input
+
 Pass content in event: `{"document_content": "<h1>Hello, World!</h1>"}`
 Pass content via URL: `{"doucment_url": "<h1>Hello, World!</h1>"}`
 
 ### Output
+
 Returns PDF base64 encoded by default.
 To save to an s3 bucket (lambda requires permission): `{"bucket_name": "<BUCKET>"}`
 To save to a presigned url: `{"presigned_url": "<URL>"}`
 
 ### Options
+
 To enable Javascript: `{"javascript": true}`
 
 ## PrinceXML License
+
 splat will attempt to install a PrinceXML license file by default. Just drop your `license.dat` in the root directory before you build the docker container. The licence file is gitignored for your convenience.
 If you do not have a licence file, Prince will watermark your PDFs, and you can only use them non-commercially. See their [license page](https://www.princexml.com/purchase/license_faq/) for more information.
 
 You can check the status of the licence by invoking the lambda with the `{"check_license": true}` option, and interpreting the response, you can use this to periodically check the status of the licence and raise an alert if it's about to expire, and to verify that your new licence has updated correctly.
 
 ## Fonts
-splat will add any fonts inside a `fonts.zip` file. Ensure the zip file contains a folder called `fonts` with all fonts inside. Simply drop into the root directory and build the docker container. The `fonts.zip` file is gitignored for your convenience. By default, prince comes with a small suite of liberation fonts.
+
+splat will add any fonts inside a `fonts.zip` file. Ensure the zip file contains a folder called `fonts` with all fonts inside. Simply drop into the root directory and build the docker container. The `fonts.zip` file is gitignored for your convenience. By default, prince comes with a small suite of liberation fonts.
+
+## Library
+
+Splat can be used via the `uptick_splat` library. Install with `pip install uptick_splat`.
+
+Usage:
+
+```python
+from uptick_splat import configure_splat, pdf_with_splat
+
+
+configure_splat(
+    function_region="ap-southeast-2",
+    function_name="splat",
+    default_bucket_name="your-bucket-to-upload-html-to",
+)
+
+some_html = "<h1>test</h1>"
+
+pdf_with_splat(some_html, bucket_name="test_bucket")
+# or
+pdf_with_splat(some_html)
+```

uptick_splat/__init__.py

@@ -1,10 +1,9 @@
-from .config import config  # noqa
+from .config import config, configure  # noqa
 from .utils import SplatPDFGenerationFailure, pdf_with_splat  # noqa
 
-__version__ = "0.1.0"
-
 __all__ = [
     "config",
+    "configure",
     "SplatPDFGenerationFailure",
     "pdf_with_splat",
     "__version__",

uptick_splat/config.py

@@ -22,15 +22,43 @@ def delete_key(bucket_name: str, path: str) -> None:
         logger.warning(f"Failed to delete {path} from s3: {e}")
 
 
+def configure_splat(
+    function_region: str = "ap-southeast-2",
+    function_name: str = "splat-prod",
+    default_bucket_name: str = "",
+    default_tagging: str = "ExpireAfter=1w",
+    get_session_fn: Callable[[], Any] = get_session,
+    delete_key_fn: Callable[[str, str], None] = delete_key,
+):
+    """Configure the splat function.
+
+    :param function_region: the default region for the splat function
+    :param function_name: the name of the splat function
+    :param default_bucket_name: the default bucket name to store html uploaded to s3
+    :param default_tagging: the default tag to apply to html uploaded to s3
+    :param get_session_fn: a function that returns a boto3 session
+    :param default_key_delete_fn: a function that deletes a key from s3
+    """
+    global config
+    config = Config(
+        function_region=function_region,
+        function_name=function_name,
+        default_bucket_name=default_bucket_name,
+        default_tagging=default_tagging,
+        get_session_fn=get_session_fn,
+        delete_key_fn=delete_key_fn,
+    )
+
+
 @dataclass
 class Config:
-    function_region: str = "ap-southeast-2"
-    function_name: str = "splat-prod"
-    default_bucket_name: str = ""
-    default_html_key: str = "ExpireAfter=1w"
+    function_region: str
+    function_name: str
+    default_bucket_name: str
+    default_tagging: str
 
-    get_session: Callable[[], Any] = get_session
-    delete_key: Callable[[str, str], None] = delete_key
+    get_session_fn: Callable[[], Any]
+    delete_key_fn: Callable[[str, str], None]
 
 
-config = Config()
+configure_splat()

uptick_splat/utils.py

@@ -34,7 +34,7 @@ def pdf_with_splat(
 
     is_streaming = not bool(s3_filepath)
 
-    session = config.get_session()
+    session = config.get_session_fn()
     lambda_client = session.client(
         "lambda", region_name=config.function_region, config=Config(read_timeout=120)
     )
@@ -62,7 +62,7 @@ def pdf_with_splat(
         Body=body_html,
         Bucket=bucket_name,
         Key=html_key,
-        Tagging="ExpireAfter=1w",
+        Tagging=config.default_tagging,
     )
 
     document_url = s3_client.generate_presigned_url(
@@ -81,7 +81,7 @@ def pdf_with_splat(
     )
 
     # Remove the temporary html file from s3
-    config.delete_key(bucket_name, html_key)
+    config.delete_key_fn(bucket_name, html_key)
 
     # Check response of the invocation. Note that a successful invocation doesn't mean the PDF was generated.
     if response.get("StatusCode") != 200:
@@ -105,7 +105,7 @@ def pdf_with_splat(
             obj = s3_client.get_object(Bucket=bucket_name, Key=destination_path)
             pdf_bytes = obj["Body"].read()
             try:
-                config.delete_key(bucket_name, destination_path)
+                config.delete_key_fn(bucket_name, destination_path)
             except Exception as e:
                 pass
             return cast(bytes, pdf_bytes)