Package: ghuc
ghucghuc(derived fromgithubusercontentand pronouncedgee·huck) is a command line tool for uploading images/documents to GitHub as issue attachments. Images are then available athttps://user-images.githubusercontent.com, and documents are available ashttps://github.com/<user>/<repo>/files/.... It automates the traditional flow of navigating to a repo -> opening an issue -> uploading an image -> copying the URL, which is very cumbersome. With the constant deterioration of Imgur, one-stop upload to user-images.githubusercontent.com is the next best thing for the occasional image embeds in docs or comment section/forum posts.ghucis partially powered by Selenium WebDriver. Tested and supported on macOS, Linux, and Windows.Please respect GitHub's ToS and do NOT abuse this tool.ContentsInstallationNon-Python dependenciesOptional dependenciesUsageEnvironment variablesHow it worksFAQTODOLicenseInstallationpip install ghucIsolated installation throughpipxis recommended.Non-Python dependenciesSinceghucuses Selenium WebDriver, one of the following browser and driver combos is required:Firefox withgeckodriver;Chrome/Chromium withchromedriver.Optional dependencieslibmagicis needed for accurate MIME type detection; otherwise, MIME types are guessed based on file extensions.Usage$ghuc-husage: ghuc [-h] [-r REPOSITORY_ID] [-x PROXY] [-q] [--debug] [--gui][--container] [--version]PATH [PATH ...]Uploads images/documents to GitHub as issue attachments. Seehttps://github.com/zmwangx/ghuc for detailed documentation.positional arguments:PATHoptional arguments:-h, --help            show this help message and exit-r REPOSITORY_ID, --repository-id REPOSITORY_IDid of repository to upload from (defaults to 1)-x PROXY, --proxy PROXYHTTP or SOCKS proxy-q, --quiet           set logging level to ERROR--debug               set logging level to DEBUG--gui                 disable headless mode when running browser sessionsthrough Selenium WebDriver--container           add extra browser options to work around problems incontainers--version             show program's version number and exitNotes:Not all file types are supported by GitHub. At the moment of writing the following, I quote, are supported:GIF, JPEG, JPG, PNG, DOCX (seriously?), GZ, LOG, PDF, PPTX, TXT, XLSX, and ZIP.The first time you useghuc, you'll be prompted for your GitHub credentials to log in (seeHow it works; you may use environment variables documented below to bypass interactive prompts). Your cookies will be cached but your credentials are never stored. Subsequent runs may phone GitHub for a new token once in a while, but ideally you should not need to log in again.--repository-id: determines what repo shows up the URL of uploaded documents. E.g., with the default1, the URL may behttps://github.com/mojombo/grit/files/3027504/random.pdf; when set to36502, one may gethttps://github.com/git/git/files/3027505/random.pdfinstead. This option is cosmetic as long as a repository exists by the id. This option has no effect on image uploads as far as I can tell.--proxy: HTTP and SOCKS (4/4a/5/5h) proxies are supported, i.e., the following protocol prefixes are recognized:http://,https://,socks4://,socks4a://,socks5://,socks5h://. If no protocol is specified,http://is assumed. Thehttps_proxyenvironment variable is also honored.--guiand--container: these are mostly development/testing options; end users don't need to touch them.--containerin particular may not be secure for end user systems.Environment variablesGITHUB_USERNAME,GITHUB_PASSWORDandGITHUB_TOTP_SECRET: interactive prompts for credentials are suppressed when these are provided.GITHUB_TOTP_SECRETis needed only if you use TOTP for two-factor authentication. If you only use text messages for 2FA (highly discouraged), the login flow might work but there's no guarantee (since I don't have a setup like this; contribution welcome). If you only use FIDO U2F for 2FA, you're out of luck.https_proxy: see--proxy.How it worksUploading files as issue attachments requires two levels of authentication: GitHub session cookies and anuploadPolicyAuthenticityToken(CSRF token of sort).uploadPolicyAuthenticityTokencan be found on any GitHub page with a comment box while logged in, and each one is valid for quite a while (without dedicated testing it's hard to say how long, but the validity period is at least more than a day).ghuclogs into GitHub through Selenium WebDriver and caches session cookies as well as the token. It then performs all uploads with the cached values and doesn't touch the browser anymore (so normal uploads should be pretty fast) until the token is stale, at which point it attempts to restore the previous browser session and fetch a new token.FAQWhy not Puppeteer?Puppeteer is way more flexible than Selenium WebDriver from a developer's point of view, but having to download a bundled, ~100MB, non-auto-updating copy of Chromium for every install that's already outdated the next time you use it is really user-hostile. I'm also not a fan of the Node/npm ecosystem. Finally, synchronous is good for this project.TODORespect proxy option in selenium invocations (currently browsers use system proxy settings);Page loads: wait forDOMContentLoadedinstead ofload(selenium default, wastes a lot time on slow connections);Handle authentication failures and allow retries (currently we assume all credentials are correct).LicenseCopyright © 2019 Zhiming Wangi@zhimingwang.org. The MIT License.