jerkup 2.0.0__tar.gz

jerkup-2.0.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.3
+Name: jerkup
+Version: 2.0.0
+Summary: Hamster Uploader
+License: MIT
+Author: deadmaster
+Author-email: deadmaster@noreply.codeberg.org
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Dist: msgspec (>=0.19.0,<0.20.0)
+Requires-Dist: platformdirs (>=4.3.7,<5.0.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Requires-Dist: requests-toolbelt (>=1.0.0,<2.0.0)
+Project-URL: Repository, https://codeberg.org/deadmaster/jerkup
+Description-Content-Type: text/markdown
+
+# Hamster Uploader
+
+## Installation
+
+Requires Python 3.13.
+
+Install using `pip install --user jerkup`.
+
+Make sure `PATH` is properly set.
+
+Generate an [API key](https://hamster.is/settings/api) and provide it using the `--api-key` option on first invocation.
+
+## Usage
+
+Upload an image and get the URL:
+
+```
+jerkup image.jpg
+```
+
+Upload multiple images:
+
+```
+jerkup image1.jpg image2.jpg
+```
+
+Output to file:
+
+```
+jerkup image.jpg --output file.txt
+```
+
+Generate BBCode linked thumbnails:
+
+```
+jerkup image.jpg --format bbcode-thumbnail-linked
+```
+
+## Reference
+
+Use `jerkup --help` to see the full documentation on options and output formats.
+

jerkup-2.0.0/README.md

@@ -0,0 +1,41 @@
+# Hamster Uploader
+
+## Installation
+
+Requires Python 3.13.
+
+Install using `pip install --user jerkup`.
+
+Make sure `PATH` is properly set.
+
+Generate an [API key](https://hamster.is/settings/api) and provide it using the `--api-key` option on first invocation.
+
+## Usage
+
+Upload an image and get the URL:
+
+```
+jerkup image.jpg
+```
+
+Upload multiple images:
+
+```
+jerkup image1.jpg image2.jpg
+```
+
+Output to file:
+
+```
+jerkup image.jpg --output file.txt
+```
+
+Generate BBCode linked thumbnails:
+
+```
+jerkup image.jpg --format bbcode-thumbnail-linked
+```
+
+## Reference
+
+Use `jerkup --help` to see the full documentation on options and output formats.

jerkup-2.0.0/jerkup/__main__.py

@@ -0,0 +1,223 @@
+import argparse
+import contextlib
+import json
+import os
+import sys
+import time
+import traceback
+import typing
+
+import requests
+
+from .configuration import has_api_key, load_api_key, save_api_key
+from .formatter import (
+	FORMAT_BBCODE_FULL,
+	FORMAT_BBCODE_FULL_LINKED,
+	FORMAT_BBCODE_MEDIUM,
+	FORMAT_BBCODE_MEDIUM_LINKED,
+	FORMAT_BBCODE_THUMBNAIL,
+	FORMAT_BBCODE_THUMBNAIL_LINKED,
+	FORMAT_DIRECT_LINK,
+	apply_format,
+	extract_format,
+)
+from .session import create_session
+from .uploader import DEFAULT_SETTINGS, Result, Settings, upload
+
+FORMAT_MAP: dict[str, str] = {
+	'direct-link': FORMAT_DIRECT_LINK,
+	'bbcode-full': FORMAT_BBCODE_FULL,
+	'bbcode-full-linked': FORMAT_BBCODE_FULL_LINKED,
+	'bbcode-medium': FORMAT_BBCODE_MEDIUM,
+	'bbcode-medium-linked': FORMAT_BBCODE_MEDIUM_LINKED,
+	'bbcode-thumbnail': FORMAT_BBCODE_THUMBNAIL,
+	'bbcode-thumbnail-linked': FORMAT_BBCODE_THUMBNAIL_LINKED,
+}
+
+
+def parse_tags(tags: str) -> list[str]:
+	if not tags:
+		return []
+	return list(map(str.strip, tags.split(',')))
+
+
+def create_parser(require_api_key: bool) -> argparse.ArgumentParser:
+	parser = argparse.ArgumentParser()
+	parser.description = 'hamster uploader'
+
+	parser.add_argument('image', type=str, nargs='+', help='path to image file')
+
+	parser.add_argument('--api-key', type=str, required=require_api_key, help='hamster api key')
+
+	parser.add_argument('--title', type=str, help='image title')
+	parser.add_argument('--description', type=str, help='image description')
+	parser.add_argument('--tags', type=parse_tags, help='comma-separated image tags')
+	parser.add_argument('--album', type=str, help='add to album with id')
+	parser.add_argument('--category', type=int, help='assign category id')
+	parser.add_argument('--width', type=int, help='target resize width')
+	parser.add_argument('--expiration', type=int, help='expiration, in seconds')
+	parser.add_argument('--nsfw', action='store_true', help='flag as nsfw')
+	parser.add_argument(
+		'--use-file-date',
+		action='store_true',
+		help='use exif date instead of upload date (admin only)',
+	)
+
+	parser.add_argument('--retry-count', type=int, default=3, help='number of retries on failure')
+	parser.add_argument('--retry-delay', type=float, default=2.0, help='delay between retries')
+
+	parser.add_argument('--output', '-o', type=str, help='output file')
+	parser.add_argument(
+		'--format',
+		'-f',
+		type=str,
+		default='direct-link',
+		choices=('json',) + tuple(FORMAT_MAP.keys()),
+		help='output format',
+	)
+
+	sub = parser.add_mutually_exclusive_group()
+	sub.add_argument(
+		'--multiline', dest='multiline', default=None, action='store_true', help='multiline output'
+	)
+	sub.add_argument('--single', dest='multiline', action='store_false', help='single line output')
+
+	return parser
+
+
+def safe_upload(
+	session: requests.Session,
+	path: typing.Union[str, os.PathLike[str]],
+	api_key: str,
+	retry: tuple[int, float],
+	output: typing.TextIO,
+	settings: Settings = DEFAULT_SETTINGS,
+) -> typing.Optional[Result]:
+	for index in range(retry[0]):
+		if index:
+			time.sleep(retry[1])
+			output.write('{} ({}/{})\n'.format(os.path.basename(path), index + 1, retry[0]))
+		else:
+			output.write('{}\n'.format(os.path.basename(path)))
+
+		try:
+			return upload(session, path, api_key, settings)
+		except Exception:
+			traceback.print_exc(file=output)
+			output.write('\n')
+
+	return None
+
+
+def dump(
+	results: list[Result],
+	output: typing.TextIO,
+	format: typing.Optional[str],
+	multiline: typing.Optional[bool],
+) -> None:
+	if multiline is None:
+		multiline = output.isatty() or format == FORMAT_DIRECT_LINK
+
+	if format is None:
+		data = list(map(extract_format, results))
+		indent = 2 if multiline else None
+
+		json.dump(data, fp=output, indent=indent)
+		output.write('\n')
+
+		return
+
+	count = 0
+	for result in results:
+		value = apply_format(result, format)
+		if value is None:
+			continue
+
+		if count and not multiline:
+			output.write(' ')
+
+		output.write(value)
+		if multiline:
+			output.write('\n')
+
+		count += 1
+
+	if count and not multiline:
+		output.write('\n')
+
+
+def execute(
+	images: typing.Iterable[typing.Union[str, os.PathLike[str]]],
+	api_key: str,
+	settings: Settings,
+	retry: tuple[int, float],
+	output_data: typing.TextIO,
+	output_text: typing.TextIO,
+	format: typing.Optional[str],
+	multiline: typing.Optional[bool],
+) -> None:
+	results: list[Result] = []
+
+	with create_session() as session:
+		for image in images:
+			result = safe_upload(session, image, api_key, retry, output_text, settings)
+
+			if result is not None:
+				results.append(result)
+
+	dump(results, output_data, format, multiline)
+
+
+def open_output(path: typing.Optional[str]) -> contextlib.AbstractContextManager[typing.TextIO]:
+	if path and path != '-':
+		return open(path, 'w', encoding='utf-8')
+	else:
+		return contextlib.nullcontext(sys.stdout)
+
+
+def main() -> None:
+	parser = create_parser(not has_api_key())
+	options = parser.parse_args()
+
+	images: list[str] = options.image
+	api_key: typing.Optional[str] = options.api_key
+	title: typing.Optional[str] = options.title
+	description: typing.Optional[str] = options.description
+	tags: typing.Optional[list[str]] = options.tags
+	album_id: typing.Optional[str] = options.album
+	category_id: typing.Optional[int] = options.category
+	width: typing.Optional[int] = options.width
+	expiration: typing.Optional[int] = options.expiration
+	nsfw: bool = options.nsfw
+	use_file_date: bool = options.use_file_date
+	retry_count: int = options.retry_count
+	retry_delay: float = options.retry_delay
+	output: typing.Optional[str] = options.output
+	format: str = options.format
+	multiline: typing.Optional[bool] = options.multiline
+
+	if api_key is None:
+		api_key = load_api_key()
+	else:
+		save_api_key(api_key)
+
+	settings = Settings(
+		title=title,
+		description=description,
+		tags=tags,
+		album_id=album_id,
+		category_id=category_id,
+		width=width,
+		expiration=expiration,
+		nsfw=nsfw,
+		use_file_date=use_file_date,
+	)
+
+	retry = (retry_count, retry_delay)
+
+	with open_output(output) as fp:
+		execute(images, api_key, settings, retry, fp, sys.stderr, FORMAT_MAP.get(format), multiline)
+
+
+if __name__ == '__main__':
+	main()

jerkup-2.0.0/jerkup/configuration.py

@@ -0,0 +1,35 @@
+import functools
+import os
+import sys
+
+import platformdirs
+
+APPLICATION = 'JerkUp' if sys.platform in ('win32', 'darwin') else 'jerkup'
+DIRECTORY = platformdirs.user_data_path(APPLICATION, False)
+
+APIKEY_NAME = 'apikey.txt'
+APIKEY_ENV = 'JERKUP_API_KEY'
+APIKEY_PATH = DIRECTORY / APIKEY_NAME
+APIKEY_ENCODING = 'utf-8'
+
+
+def has_api_key() -> bool:
+	return APIKEY_ENV in os.environ or APIKEY_PATH.is_file()
+
+
+def load_api_key() -> str:
+	value = os.environ.get(APIKEY_ENV)
+	if value is not None:
+		return value
+
+	with APIKEY_PATH.open('r', encoding=APIKEY_ENCODING) as fp:
+		value = fp.readline().rstrip('\n')
+	return value
+
+
+def save_api_key(api_key: str) -> None:
+	DIRECTORY.mkdir(parents=True, exist_ok=True)
+
+	opener = functools.partial(os.open, mode=0o660)
+	with open(APIKEY_PATH, mode='w', encoding=APIKEY_ENCODING, opener=opener) as fp:
+		fp.write(api_key)

jerkup-2.0.0/jerkup/formatter.py

@@ -0,0 +1,26 @@
+import dataclasses
+import typing
+
+from .uploader import Result
+
+FORMAT_DIRECT_LINK = '{image}'
+FORMAT_BBCODE_FULL = '[img]{image}[/img]'
+FORMAT_BBCODE_FULL_LINKED = '[url={viewer}][img]{image}[/img][/url]'
+FORMAT_BBCODE_MEDIUM = '[img]{medium}[/img]'
+FORMAT_BBCODE_MEDIUM_LINKED = '[url={viewer}][img]{medium}[/img][/url]'
+FORMAT_BBCODE_THUMBNAIL = '[img]{thumbnail}[/img]'
+FORMAT_BBCODE_THUMBNAIL_LINKED = '[url={viewer}][img]{thumbnail}[/img][/url]'
+
+
+def extract_format(result: Result) -> dict[str, object]:
+	data = dataclasses.asdict(result)
+	if result.medium is None:
+		data.pop('medium')
+	return data
+
+
+def apply_format(result: Result, format: str) -> typing.Optional[str]:
+	try:
+		return format.format(**extract_format(result))
+	except KeyError:
+		return None

jerkup-2.0.0/jerkup/iso8601.py

@@ -0,0 +1,39 @@
+import datetime
+import typing
+
+
+# https://en.wikipedia.org/wiki/ISO_8601#Durations
+def format_duration(duration: typing.Union[datetime.timedelta, int]) -> str:
+	if isinstance(duration, datetime.timedelta):
+		duration = duration.days * 86400 + duration.seconds
+
+	parts: list[typing.Union[str, int]] = []
+	seconds = duration
+
+	minutes, seconds = divmod(seconds, 60)
+	hours, minutes = divmod(minutes, 60)
+	days, hours = divmod(hours, 24)
+
+	if seconds or not (minutes or hours or days):
+		parts.append('S')
+		parts.append(seconds)
+
+	if minutes:
+		parts.append('M')
+		parts.append(minutes)
+
+	if hours:
+		parts.append('H')
+		parts.append(hours)
+
+	if parts:
+		parts.append('T')
+
+	if days:
+		parts.append('D')
+		parts.append(days)
+
+	parts.append('P')
+	parts.reverse()
+
+	return ''.join(map(str, parts))

jerkup-2.0.0/jerkup/messages.py

@@ -0,0 +1,31 @@
+import typing
+
+import msgspec
+
+TStr = typing.TypeVar('TStr', str, typing.Optional[str])
+
+
+class Status(msgspec.Struct):
+	message: str
+	code: typing.Union[int, str]
+
+
+class Image(typing.Generic[TStr], msgspec.Struct):
+	url: TStr
+
+
+class Body(msgspec.Struct):
+	url_viewer: str
+	image: Image[str]
+	thumb: Image[str]
+	medium: Image[typing.Optional[str]]
+
+
+class Response(msgspec.Struct):
+	status_code: int
+	success: Status
+	image: Body
+	status_txt: str
+
+
+DECODER = msgspec.json.Decoder(Response)

jerkup-2.0.0/jerkup/session.py

@@ -0,0 +1,25 @@
+import functools
+import importlib.metadata
+import platform
+
+import requests
+
+
+@functools.cache
+def get_user_agent() -> str:
+	parts: tuple[str, ...] = (
+		'{}/{}'.format(__package__, importlib.metadata.version(__package__)),
+		'Python {}'.format(platform.python_version()),
+		'{} {}'.format(platform.system(), platform.release()),
+		platform.machine(),
+		'+https://codeberg.org/deadmaster/jerkup',
+	)
+
+	return '{} ({})'.format(parts[0], '; '.join(parts[1:]))
+
+
+def create_session() -> requests.Session:
+	session = requests.Session()
+	session.headers['User-Agent'] = get_user_agent()
+	session.stream = True
+	return session

jerkup-2.0.0/jerkup/uploader.py

@@ -0,0 +1,90 @@
+import dataclasses
+import datetime
+import mimetypes
+import os
+import typing
+
+import requests
+import requests_toolbelt  # type: ignore[import-untyped]
+
+from .iso8601 import format_duration
+from .messages import DECODER
+
+ENDPOINT = 'https://hamster.is/api/1/upload'
+TIMEOUT = (10.0, 30.0)
+
+
+# https://v4-docs.chevereto.com/developer/api/api-v1.html
+@dataclasses.dataclass(eq=False, frozen=True, kw_only=True)
+class Settings:
+	title: typing.Optional[str] = None
+	description: typing.Optional[str] = None
+	tags: typing.Optional[list[str]] = None
+	album_id: typing.Optional[str] = None
+	category_id: typing.Optional[int] = None
+	width: typing.Optional[int] = None
+	expiration: typing.Union[datetime.timedelta, int, None] = None
+	nsfw: typing.Optional[bool] = None
+	use_file_date: typing.Optional[bool] = None
+
+
+DEFAULT_SETTINGS = Settings()
+
+
+@dataclasses.dataclass(eq=False, frozen=True, kw_only=True)
+class Result:
+	viewer: str
+	image: str
+	medium: typing.Optional[str] = None
+	thumbnail: str
+
+
+def upload(
+	session: requests.Session,
+	path: typing.Union[str, os.PathLike[str]],
+	api_key: str,
+	settings: Settings = DEFAULT_SETTINGS,
+) -> Result:
+	mimetypes.init()
+	mime_type, _ = mimetypes.guess_type(path)
+	if mime_type is None:
+		raise ValueError('unknown file type')
+
+	with open(path, 'rb') as fp:
+		fields: dict[str, typing.Union[str, tuple[str, typing.BinaryIO, str]]] = {}
+		fields['source'] = (os.path.basename(path), fp, mime_type)
+		if settings.title is not None:
+			fields['title'] = settings.title
+		if settings.description is not None:
+			fields['description'] = settings.description
+		if settings.tags is not None:
+			fields['tags'] = ','.join(settings.tags)
+		if settings.album_id is not None:
+			fields['album_id'] = settings.album_id
+		if settings.category_id is not None:
+			fields['category_id'] = str(settings.category_id)
+		if settings.width is not None:
+			fields['width'] = str(settings.width)
+		if settings.expiration is not None:
+			fields['expiration'] = format_duration(settings.expiration)
+		if settings.nsfw is not None:
+			fields['nsfw'] = str(int(settings.nsfw))
+		fields['format'] = 'json'
+		if settings.use_file_date is not None:
+			fields['use_file_date'] = str(int(settings.use_file_date))
+
+		encoder = requests_toolbelt.MultipartEncoder(fields)
+		headers = {'X-API-Key': api_key, 'Content-Type': encoder.content_type}
+
+		with session.post(
+			ENDPOINT, data=encoder, headers=headers, timeout=TIMEOUT, allow_redirects=False
+		) as response:
+			response.raise_for_status()
+			data = DECODER.decode(response.content)
+
+	return Result(
+		viewer=data.image.url_viewer,
+		image=data.image.image.url,
+		medium=data.image.medium.url,
+		thumbnail=data.image.thumb.url,
+	)

jerkup-2.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[tool.poetry]
+name = "jerkup"
+version = "2.0.0"
+description = "Hamster Uploader"
+license = "MIT"
+authors = ["deadmaster <deadmaster@noreply.codeberg.org>"]
+readme = "README.md"
+repository = "https://codeberg.org/deadmaster/jerkup"
+classifiers = ["Topic :: Internet :: WWW/HTTP"]
+
+[tool.poetry.dependencies]
+python = "^3.13"
+requests = "^2.32.3"
+requests-toolbelt = "^1.0.0"
+msgspec = "^0.19.0"
+platformdirs = "^4.3.7"
+
+[tool.poetry.group.dev.dependencies]
+mypy = "^1.15.0"
+ruff = "^0.11.8"
+types-requests = "^2.32.0"
+
+[tool.poetry.scripts]
+jerkup = "jerkup.__main__:main"
+
+[tool.ruff]
+include = ["jerkup/**/*.py"]
+target-version = "py313"
+line-length = 100
+indent-width = 4
+
+[tool.ruff.lint]
+select = ["F", "I", "UP", "G"]
+ignore = ["UP007", "UP015", "UP032", "UP038"]
+
+[tool.ruff.lint.isort]
+split-on-trailing-comma = false
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "tab"
+skip-magic-trailing-comma = true
+
+[tool.mypy]
+python_version = "3.13"
+show_error_codes = true
+show_absolute_path = true
+files = ["jerkup"]
+strict = true
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"