{"id":35204721,"url":"https://github.com/izxxr/nutshell","last_synced_at":"2026-05-01T05:39:51.616Z","repository":{"id":255753211,"uuid":"852975484","full_name":"izxxr/nutshell","owner":"izxxr","description":"Pocket sized link shortener written in Python","archived":false,"fork":false,"pushed_at":"2024-10-15T20:51:05.000Z","size":29,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-01T05:39:36.111Z","etag":null,"topics":["coding","flask","link-shortener","linkshortener","python","quart","web","web-app","web-development"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/izxxr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-05T18:54:25.000Z","updated_at":"2024-10-15T20:51:09.000Z","dependencies_parsed_at":"2024-09-13T15:17:56.334Z","dependency_job_id":"a44841a3-81e2-4af1-9628-077fb21aabf0","html_url":"https://github.com/izxxr/nutshell","commit_stats":null,"previous_names":["izxxr/nutshell"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/izxxr/nutshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izxxr%2Fnutshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izxxr%2Fnutshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izxxr%2Fnutshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izxxr%2Fnutshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/izxxr","download_url":"https://codeload.github.com/izxxr/nutshell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izxxr%2Fnutshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32486222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coding","flask","link-shortener","linkshortener","python","quart","web","web-app","web-development"],"created_at":"2025-12-29T13:12:23.152Z","updated_at":"2026-05-01T05:39:51.611Z","avatar_url":"https://github.com/izxxr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nutshell\n[Nutshell](https://izxxr.medium.com/writing-a-pocket-sized-url-shortener-in-python-a1f9ab64b14a) (as the name implies) is a\npocket-sized, simple link shortener written in Python using Quart.\n\nThis is a personal link shortener that was written within the span of two hours and provides the\nfollowing features:\n\n- Random, concise and support for custom URLs\n- Password protected URLs\n- Temporary link deactivation\n- URL metrics (total visits, successful visits, last visit etc.)\n- API interface for CRUD operations on links\n- Internal LRU cache to regulate database transactions\n\n## Installation\n_Python 3.8 or higher is required._\n\nClone this repository and install the dependencies:\n\n```\n$ git clone https://github.com/izxxr/nutshell\n$ cd nutshell\n$ pip install -r requirements.txt\n```\n\nCreate an `.env` file and define a `NUTSHELL_AUTH_TOKEN` environment variable. This variable\nstores the authentication token that will be sent to API to create, read, update and delete\nURLs. Make sure to use a strong combination of characters. It has to be greater than 10 characters.\n\n`.env` file:\n\n```\nNUTSHELL_AUTH_TOKEN=\"...\"\n```\n\nOther optional variables to control the application behaviour are:\n\n- `NUTSHELL_CACHE_LIMIT`: The number of links cached in memory at a time. Upon exceeding this numbers,\n  least recently used links are evicted from cache. Default value is 50.\n\nRun the application on local development server:\n\n```\n$ quart run\n```\n\nUse the following options in run command to manipulate various server options:\n\n- `-h` or `--host`: The host to bind to.\n- `-p` or `--port`: The port number to bind to.\n- `--reload`/`--no-reload`: Whether to enable or disable reloader (disabled by default).\n\n## Link Object\nOn the heart of nutshell is the **link** object that represents a shortened URL. Following\nfields are part of the link object:\n\n- `code`: The unique link code.\n- `url`: The URL that the link redirects to. (only HTTP/HTTPs URLs allowed)\n- `password`: The password to access this link, if any, otherwise null.\n- `created_at`: The time, in ISO format, when the link was created.\n- `last_visited`: The time, in ISO format, when the link was last visited.\n- `active`: Whether the link is active and redirecting. If false, the link is temporarily disabled.\n- `raw_visit_count`: The number of times link was accessed.\n- `visit_count`: The number of times link was accessed *successfully*.\n\n`visit_count` and `raw_visit_count` are same for unauthorized links. For password protected links, `raw_visit_count`\nindicates the number of times the link was accessed regardless of whether password was entered correctly or not and\n`visit_count` indicates the number of times password was entered correctly.\n\n## CRUD operations\nThe following routes are used for managing links.\n\nAll sub-routes in `/links` require authorization using bearer token in the `Authorization`\nheader. The value for this header should use `Bearer` scheme followed by the authorization token\nthat was set in .env file during installation. E.g. `Bearer ABCDEFGHIJKL123456789`\n\nIf this header is omitted, `401: Unauthorized` is returned. If the authorization token is invalid,\n`403: Forbidden` is returned. `404: Not Found` and `400: Bad Request` are returned, respectively, when\na link does not exist and when given request data is invalid.\n\n### POST `/links` - Create a link\nCreates a link.\n\nThe following parameters are to be passed in JSON body:\n\n- `url` (required): the URL that shortened link points to.\n- `code`: The custom code for this link. If not provided, a random six digits code is generated.\n- `active`: Whether the link is created as active.\n- `password`: The password to access this link, if any.\n\n`code` cannot be changed once created. If `code` is taken, `409: Conflict` is returned.\n\nReturns the created link object.\n\n### GET `/links` - Get All Links\nReturns the list of link objects representing all created links.\n\n### GET `/links/\u003ccode\u003e` - Get Link\nReturns the link object corresponding to the given `code`.\n\n### PATCH `/links/\u003ccode\u003e` - Update Link\nUpdates a link.\n\nThe following parameters are to be passed in JSON body:\n\n- `url`: the URL that shortened link points to.\n- `active`: Whether the link is active.\n- `password`: The password to access this link, if any. Set null to remove password.\n\nReturns the updated link object.\n\n### DELETE `/links/\u003ccode\u003e` - Delete Link\nDeletes a link.\n\nReturns `204: No Content` on successful deletion.\n\n## Accessing links\nThe links can be accessed by using the shortened URL code on index. For example, if Nutshell is\nhosted on localhost at port 5000, the link `ABCDEF` can be accessed by accessing http://localhost:5000/ABCDEF\n\nIf a URL is password protected, the user will be required to enter a password before being able\nto redirect to the target URL.\n\n## License and Contributions\nAny pull requests and issues, small or large, are welcome. For license information, see `LICENSE` file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fizxxr%2Fnutshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fizxxr%2Fnutshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fizxxr%2Fnutshell/lists"}