Merge pull request #6 from sov2000/image-ftr-1

v1.0.2 commit - adding new commands and some bug fixes

Author: sov2000

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Change Log
 
+## [1.0.2] - 2024-12
+
+### Added
+- User command to display authenticated user and other user info by ID
+- Shop command to pull info about a shop by its IP, user ID, and search by name
+- Image command with full support for get, upload, update, and delete
+- Listing Property command with support to retrieve, update, and delete values
+
+### Updated
+- Minor bug fixes and documentation updates
+
 ## [1.0.1] - 2024-12
 
 ### Added

README.md

@@ -62,6 +62,46 @@ Before you can use the app, you will need to obtain an API key from Etsy. You ca
     - E.g. `ETSPI_KEY=YOU_ETSY_APP_KEYSTRING` or `ETSPI_TOKEN=YOUR_AUTH_TOKEN`.
     - Command line options take precedence over the env variables and variables take precedence over the values stored in the `Auth.env` file.
 
+## User:
+
+Retrieve current authenticated user ID and Shop ID.
+
+```bash
+etspi user
+```
+
+More User details can be retrieved for a specific User ID.
+
+```bash
+etspi user -u 123456789
+```
+
+## Shop:
+
+Retrieve detailed shop info by Shop Id.
+
+```bash
+etspi shop-get -s 12345678
+```
+
+Same as before but pull info by User ID instead.
+
+```bash
+etspi shop-get -u 123456789
+```
+
+Alternatively, search by Shop Name performing typical partial name search.
+
+```bash
+etspi shop-get -n Paint
+```
+
+Since you the number of the results can be quite large, `-R` option can be used to limit and offset the results with the first number as the `offset` and the second number as the `limit` to retrieve.
+
+```bash 
+etspi shop-get -n Paint -R 9 1
+```
+
 ## Listing:
 
 ### listing-get
@@ -106,7 +146,7 @@ etspi listing-update -i 1800000081 -s 10000001 -f my_listing_update.json
 
 ### listing-delete
 
-This is self-explanatory and will delete a listing by Id. Use `-Y` or `--yes` flat to suppress ***confirmation prompt*** before making the API call to delete the listing!
+This is self-explanatory and will delete a listing by Id. Use `-Y` or `--yes` flag to suppress ***confirmation prompt*** before making the API call to delete the listing!
 
 ```bash
 etspi listing-delete -i 1800000081 -Y
@@ -140,6 +180,74 @@ Use to update the listing inventory with the values from a JSON source file spec
 etspi listing-update-iv -i 1800000081 -f my_listing_update.json
 ```
 
+## Images:
+
+### image-get
+
+Display all listing Images with IDs, URLs, and other metadata.
+
+```bash
+etspi image-get -i 1800000081
+```
+
+Or if information is only needed for one image, pull it by Image ID in addition to the listing ID.
+
+```bash
+etspi image-get -i 1800000081 -ii 6123123123
+```
+### image-upload
+
+Upload a new image and add it to the listing at the specified `rank` with option `-r` and `-a` for alternate text. If you are uploading into existing `rank`, you will need `-O` option to allow overwriting of the content.
+
+```bash
+etspi image-upload -i 1800000081 -s 12345678 -f "path\to\my\Listing_Image_File.jpg" -r 5 -a "Tree print wall art"
+```
+
+### image-delete
+
+Delete an image from listing by Image Id. Use `-Y` or `--yes` flag to suppress ***confirmation prompt*** before making the API call to delete.
+
+```bash
+etspi image-delete -i 1800000081 -ii 6123123123
+```
+
+## Properties:
+
+### prop-get:
+
+To retrieve all properties for a listing.
+
+```bash
+etspi prop-get -i 1800000081 -s 12345678
+```
+
+To retrieve a specific property (with ID 98765432) for a listing
+
+```bash
+etspi prop-get -i 1800000081 -s 12345678 -pi 98765432
+```
+
+To retrieve all properties for a listing and save the output to a file named "listing_properties.json"
+
+```bash
+etspi prop-get -i 1800000081 -s 12345678 -o listing_properties.json
+```
+
+To retrieve all properties for a listing, format the output for a listing property update request, and save the output to a file named "listing_property_update.json"
+
+```bash
+etspi prop-get -i 1800000081 -s 12345678 --format-update -o listing_property_update.json
+```
+
+### prop-update
+
+To update a property for listing, you will need a JSON file in the correct update format. Use the `prop-get` command to generte a file you can modify in the correct format.
+
+
+```bash
+etspi prop-update -i 1800000081 -s 12345678 -pi 98765432 -f listing_property_update.json
+```
+
 ## Note on STDOUT redirects
 
 Etspi console output uses `rich` library `print` which will color code and format JSON for more esthetic and readable output. When using Etspi `--out` you get original formatted JSON which is what you want for subsequent commands and API calls. If you have a need to pipe or redirect Etspi output to a different console app or file, you may want this original JSON and not pretty formatted. In that case, consider using `--out` to STDOUT `-` with `-S` and apply your pipe or redirect this way.

etspi/cli.py

@@ -10,7 +10,7 @@
 
 import click
 
-__version__ = "1.0.1"
+__version__ = "1.0.2"
 
 # Click context and environment utility class
 class Environment:
@@ -136,6 +136,7 @@ def show_auth_params(root: click.Context, ctx: Any) -> None:
 @click.option("-E", "--expiry", required=False, help="API access token future expiration timestamp.")
 @click.option("-nP", "--no-persist", is_flag=True, default=False, help="Do not update auth.env file when tokens are refreshed. By default, if the file exists, new tokens are automatically saved.")
 @click.option("-v", "--verbose", is_flag=True, help="Enables verbose output mode.")
+@click.version_option(version=__version__, message='%(prog)s, version %(version)s')
 @pass_environment
 @click.pass_context
 def cli(root: Any, ctx: Any, token: Any, refresh_token: Any, key: Any, expiry: Any, no_persist: bool, verbose: Any) -> None:

etspi/commands/cmd_auth.py

@@ -110,7 +110,7 @@ def start_httpd_service(ctx: Any, host: str, port: int, certfile: str, keyfile:
 
 def check_all_scopes(scopes: List) -> List:
     if "all" in scopes:
-        return ["feedback_r", "listings_d", "listings_r", "listings_w", "shops_r", "shops_w", "transactions_r", "transactions_w"]
+        return ["email_r", "listings_d", "listings_r", "listings_w", "shops_r", "shops_w", "transactions_r", "transactions_w"]
     return scopes
 
 def get_auth_directions(ctx: Any, auth_hlp: AuthHelper, rdr_url: str, scope_list: list) -> None:
@@ -136,7 +136,7 @@ def get_auth_directions(ctx: Any, auth_hlp: AuthHelper, rdr_url: str, scope_list
               default=os.path.join(os.path.expanduser('~'), ".etspi\\key.pem"), 
               help="Callback server SSL key file location.")
 @click.option("-s", "--scope", multiple=True, default=["all"],
-              type=click.Choice(["all", "feedback_r", "listings_d", "listings_r", "listings_w", "shops_r", "shops_w", "transactions_r", "transactions_w"], case_sensitive=True), 
+              type=click.Choice(["all", "email_r", "listings_d", "listings_r", "listings_w", "shops_r", "shops_w", "transactions_r", "transactions_w"], case_sensitive=True), 
               help="Specify scope options to request for authorization or 'all' for all currently supported scopes.")
 @click.option("-tF", "--token-file", is_flag=True, default=False, help="Write out the tokens to the auth.env file.")
 @click.option("-tH", "--token-hidden", is_flag=True, default=False, help="Supress the output of the tokens to the console.")

etspi/commands/cmd_draft.py

@@ -9,7 +9,7 @@
 from etspi.etsyv3 import EtsyAPI, Includes
 from etspi.etsyv3.models import CreateDraftListingRequest
 
-def draft_listing(ctx: Any, shop_id: str, src_file: Any, silent: bool) -> None:
+def draft_listing(ctx: Any, shop_id: int, src_file: Any, silent: bool) -> None:
     pld = json.load(src_file)
     etsy = ctx.get_etsy("DRAFT")
     if "type" in pld:

etspi/commands/cmd_image-delete.py

@@ -0,0 +1,40 @@
+import click
+
+from typing import Any, Dict, List, Optional
+from rich import print
+from etspi.cli import pass_environment, Environment
+from etspi.etsyv3 import EtsyAPI, Includes
+
+def delete_listing_image(ctx: Any, id: int, shop_id: int, img_id: int, yes: bool, silent: bool) -> None:
+    ctx.vlog(f"Delete Action for Listing ID: {id} and Image ID: {img_id}")
+    etsy = ctx.get_etsy("IMAGE-DELETE")
+    confirm = True
+    if not yes:
+        user_input = input(f"Are you sure you want to delete image {img_id} from listing {id}? (yes/no):")
+        if user_input.lower() not in ['yes', 'y']:
+            confirm = False 
+    if confirm:
+        ctx.vlog(f"Deleting Image ID: {img_id} from Listing ID: {id}")
+        res = etsy.delete_listing_image(shop_id, id, img_id)
+        if not silent:
+            print(res)
+    else:
+        ctx.vlog(f"Abort Delete Image ID: {img_id} from Listing ID: {id}")
+    return
+
+@click.command("image-delete", short_help="Delete listing image by Image and Listing ID")
+@click.option("-i", "--id", required=True, type=click.INT, help="Listing ID to which apply action.")
+@click.option("-s", "--shop-id", required=False, type=click.INT, help="Shop ID to use for update and other actions.")
+@click.option("-ii", "--img-id", required=True, type=click.INT, help="Image ID to delete.")
+@click.option("-Y", "--yes", required=False, default=False, is_flag=True, help="Do not ask to confirm image delete.")
+@click.option("-S", "--silent", required=False, default=False, is_flag=True, help="Supress console output.")
+@pass_environment
+def cli(ctx, id, shop_id, img_id, yes, silent):
+    """Perform a Delete action on a listing by Listing and Image IDs."""
+    ctx.check_auth("IMAGE-DELETE")
+    if not id is None:
+        ctx.vlog(f"Process DELETE IMAGE listing: {id}")
+    try:
+        delete_listing_image(ctx, id, shop_id, img_id, yes, silent)
+    except Exception as ex:
+        ctx.log(f"Error processing command - {ex}")

etspi/commands/cmd_image-get.py

@@ -0,0 +1,41 @@
+import json
+import click
+import jmespath
+
+from typing import Any, Dict, List, Optional
+from rich import print
+from etspi.cli import pass_environment, Environment
+from etspi.etsyv3 import EtsyAPI
+
+def get_listing_image(ctx: Any, id: int, img_id: int, query: str, out: Any, silent: bool) -> None:
+    ctx.vlog(f"Get Image Action for Listing ID: {id} Image ID: {img_id}")
+    etsy = ctx.get_etsy("LISTING-GET")
+    if img_id > 0:
+        res = etsy.get_listing_image(id, img_id)
+    else:
+        res = etsy.get_listing_images(id)
+    if res:
+        if query:
+            res = jmespath.search(query, res)
+        if out:
+            out.write(json.dumps(res, indent=4))
+        if not silent:
+            print(res)
+    return
+
+@click.command("image-get", short_help="Retrieve or Get listing image(s) by Image and Listing ID")
+@click.option("-i", "--id", required=True, type=click.INT, help="Listing ID from which to retrieve the image.")
+@click.option("-ii", "--img-id", required=False, default=0, type=click.INT, help="Image ID to retrieve or, if omitted or 0, get all images.")
+@click.option("-q", "--query", type=click.STRING, help="JMESPath query to filter the output of the command.")
+@click.option("-o", "--out", required=False, type=click.File(mode="w", encoding="utf-8", errors="strict", lazy=None, atomic=False), help="Also output result into a file.")
+@click.option("-S", "--silent", required=False, default=False, is_flag=True, help="Supress console output.")
+@pass_environment
+def cli(ctx, id, img_id, query, out, silent):
+    """Perform a GET IMAGE action on a listing by Listing ID and optional Image ID."""
+    ctx.check_auth("IMAGE-GET")
+    if not id is None:
+        ctx.vlog(f"Process GET Image Listing ID: {id} Image ID: {img_id}")
+    try:
+        get_listing_image(ctx, id, img_id, query, out, silent)
+    except Exception as ex:
+        ctx.log(f"Error processing command - {ex}")

etspi/commands/cmd_image-upload.py

@@ -0,0 +1,48 @@
+import click
+
+from typing import Any, Dict, List, Optional
+from rich import print
+from etspi.cli import pass_environment, Environment
+from etspi.etsyv3 import EtsyAPI, Includes
+from etspi.etsyv3.models import UploadListingImageRequest, UpdateListingImageIDRequest
+
+def upload_listing_image(ctx: Any, id: int, shop_id: int, src_file: Any, img_id: int, rank: int,
+                        overwrite: bool, watermark: bool, alt_text: str, silent: bool) -> None:
+    ctx.vlog(f"Upload or Update Image Action for Listing ID: {id} Image ID {img_id}")
+    etsy = ctx.get_etsy("LISTING-UPDATE")
+    if not src_file is None:
+        img_content = src_file.read()
+        listing_img = UploadListingImageRequest(image_bytes = img_content, listing_image_id = img_id, rank = rank, overwrite = overwrite, 
+                                                is_watermarked = watermark, alt_text = alt_text)
+        res = etsy.upload_listing_image(shop_id, id, listing_img)
+    elif not img_id is None:
+        listing_img = UpdateListingImageIDRequest(listing_image_id = img_id, rank = rank, overwrite = overwrite,
+                                                is_watermarked = watermark, alt_text = alt_text)
+        res = etsy.update_listing_image_id(shop_id, id, listing_img)
+    else:
+        raise click.BadArgumentUsage("No Source File or Image Id provided for upload or update.") 
+    if not silent:
+        print(res)
+    return
+
+@click.command("image-upload", short_help="Upload a new listing image or update by Image ID")
+@click.option("-i", "--id", required=True, type=click.INT, help="Listing ID to which apply action.")
+@click.option("-s", "--shop-id", required=False, type=click.INT, help="Shop ID to use for update and other actions.")
+@click.option("-f", "--src-file", required=False, help="Source image file from which to read content to upload.",
+              type=click.File(mode="rb", encoding="utf-8", errors="strict", lazy=None, atomic=False))
+@click.option("-ii", "--img-id", required=False, default=1, type=click.INT, help="Image ID to update for existing.")
+@click.option("-r", "--rank", required=False, default=1, type=click.INT, help="Image rank to upload or update.")
+@click.option("-O", "--overwrite", required=False, default=False, is_flag=True, help="Overwrite file flag to replace existing image.")
+@click.option("-W", "--watermark", required=False, default=False, is_flag=True, help="Set to indicate image has a watermark.")
+@click.option("-a", "--alt-text", required=False, default="", type=click.STRING, help="Image ALT Text to set upon upload or update.")
+@click.option("-S", "--silent", required=False, default=False, is_flag=True, help="Supress console output.")
+@pass_environment
+def cli(ctx, id, shop_id, src_file, img_id, rank, overwrite, watermark, alt_text, silent):
+    """Upload a new image or Update existing image by Listing ID and Image ID."""
+    ctx.check_auth("IMAGE-UPLOAD")
+    if not id is None:
+        ctx.vlog(f"Process Upload or Update Image Listing ID: {id} Image ID: {img_id}")
+    try:
+        upload_listing_image(ctx, id, shop_id, src_file, img_id, rank, overwrite, watermark, alt_text, silent)
+    except Exception as ex:
+        ctx.log(f"Error processing command - {ex}")

etspi/commands/cmd_listing-delete.py

@@ -5,7 +5,7 @@
 from etspi.cli import pass_environment, Environment
 from etspi.etsyv3 import EtsyAPI, Includes
 
-def delete_listing(ctx: Any, id: str, yes: bool, silent: bool) -> None:
+def delete_listing(ctx: Any, id: int, yes: bool, silent: bool) -> None:
     ctx.vlog(f"Delete Action for Listing ID: {id}")
     etsy = ctx.get_etsy("LISTING-DELETE")
     confirm = True

etspi/commands/cmd_listing-get-iv.py

@@ -8,7 +8,7 @@
 from etspi.etsyv3 import EtsyAPI, Includes
 from etspi.etsyv3.models import UpdateListingInventoryRequest
 
-def get_listing_inventory(ctx: Any, id: str, transform: str, query: str, out: Any, silent: bool) -> None:
+def get_listing_inventory(ctx: Any, id: int, transform: str, query: str, out: Any, silent: bool) -> None:
     ctx.vlog(f"Get Inventroy Action for Listing ID: {id}")
     etsy = ctx.get_etsy("LISTING-GET-IV")
     res = etsy.get_listing_inventory(id)
@@ -25,7 +25,6 @@ def get_listing_inventory(ctx: Any, id: str, transform: str, query: str, out: An
 
 @click.command("listing-get-iv", short_help="Retrieve or Get a listing inventory by ID")
 @click.option("-i", "--id", required=True, type=click.INT, help="Listing ID to which apply action.")
-#@click.option("-t", "--transform", is_flag=True, default=False, help="Transform listing or inventory response into format suitable for update inventory request.")
 @click.option("--format-update", "transform", flag_value="update", default=False, help="Transform listing response into format suitable for listing update request.")
 @click.option("-q", "--query", type=click.STRING, help="JMESPath query to filter the output of the command.")
 @click.option("-o", "--out", required=False, type=click.File(mode="w", encoding="utf-8", errors="strict", lazy=None, atomic=False), help="Also output result into a file")