{"id":20778723,"url":"https://github.com/lucianoayres/rjip","last_synced_at":"2026-05-16T17:08:34.760Z","repository":{"id":248448945,"uuid":"828713939","full_name":"lucianoayres/rjip","owner":"lucianoayres","description":"Command-line tool designed to pick a random item from a JSON file while ensuring that each item is picked only once. ","archived":false,"fork":false,"pushed_at":"2024-07-28T22:30:46.000Z","size":6113,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-18T08:36:35.646Z","etag":null,"topics":["cli","json","python","random-item"],"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/lucianoayres.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-07-15T01:07:18.000Z","updated_at":"2024-07-28T22:30:49.000Z","dependencies_parsed_at":"2024-07-15T02:29:57.620Z","dependency_job_id":"185df1d4-9ef5-4fa2-b372-1cf9c79fff2e","html_url":"https://github.com/lucianoayres/rjip","commit_stats":null,"previous_names":["lucianoayres/rjip"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucianoayres%2Frjip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucianoayres%2Frjip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucianoayres%2Frjip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucianoayres%2Frjip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucianoayres","download_url":"https://codeload.github.com/lucianoayres/rjip/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243119538,"owners_count":20239321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","json","python","random-item"],"created_at":"2024-11-17T13:23:47.152Z","updated_at":"2026-05-16T17:08:29.722Z","avatar_url":"https://github.com/lucianoayres.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![rJip_logo](https://github.com/user-attachments/assets/cc0c916c-ca2f-4345-9b98-739d666e34a4)\n\n# rJip: Random JSON Item Picker\n\nCommand-line tool designed to pick a random item from a JSON file while ensuring that each item is picked only once. It keeps track of previously picked items to maintain uniqueness until all items have been picked at least once.\n\n## Demo\n\n![rjip_demo](https://github.com/user-attachments/assets/b95c8c24-833f-472a-a0b9-831c55aa5ab0)\n\n## Features\n\n-   Random Item Selection: Retrieves a random item from a specified JSON file.\n-   Tracking Last Picks: Maintains a record of previously picked items to avoid duplicates.\n-   Property Validation: Validates a specified property name within the JSON data.\n-   Error Handling: Includes specific error codes for different validation and operational errors.\n\n## Usage\n\nTo use the tool, execute `rjip` binary file in the `dist` directory with the following parameters:\n\n```bash\n$ ./rjip [input_file] [property_name] [last_pick_file] [--no-update]\n```\n\n### Arguments\n\n-   `input_file`: The path to the input JSON file containing the items to be picked.\n-   `property_name`: A property name to validate within the JSON items.\n-   `last_pick_file`: An optional file to store the last picked items (default: none). If no last_pick_file is specified, a new file will be created using the input file name as a prefix.\n-   `--no-update`: A flag to disable updating the file that stores the last picked items.\n\n## Example\n\n### 1. Prepare the Input File\n\nCreate an input file (e.g., `data.json`) with the desired data:\n\n```json\n[\n    { \"id\": 1, \"name\": \"Item 1\" },\n    { \"id\": 2, \"name\": \"Item 2\" },\n    { \"id\": 3, \"name\": \"Item 3\" },\n    { \"id\": 4, \"name\": \"Item 4\" },\n    { \"id\": 5, \"name\": \"Item 5\" }\n]\n```\n\n### 2. Run the Program\n\nExecute the program, specifying the unique `property_name` key (e.g., `id`) and the file where the selected items will be stored (e.g., `last_picks.json`)\n\n```bash\n$ ./rjip data.json id last_picks.json\n```\n\n### 3. View the Output\n\nThe program will output a randomly selected item in JSON format:\n\n```json\n{\n    \"status\": \"success\",\n    \"item\": {\n        \"id\": 3,\n        \"name\": \"Item 3\"\n    }\n}\n```\n\n### 4. Save the Picked Item\n\nThe selected item will be saved in the `last_picks.json` file to ensure it won't be picked again:\n\n#### Contents of last_picks.json after the first run:\n\n```json\n[{ \"id\": 3, \"name\": \"Item 3\" }]\n```\n\n### 5. Repeat Until All Items Are Picked\n\nRun the program again to pick another item, continuing until all items have been picked. The program will manage the selection process to ensure that each item is only picked once.\n\n## Error Codes\n\nBelow is a list of possible error codes and their descriptions:\n\n-   `invalid_or_nonexistent_json_file`: Indicates an invalid or non-existent JSON file path.\n-   `empty_input_json_file`: Indicates an empty input JSON file.\n-   `invalid_property_name`: Indicates an invalid property name provided.\n-   `all_items_picked`: Indicates that all items have been picked and no new items are available.\n-   `generic_error`: Indicates an unexpected error occurred.\n\n### Example Error Response\n\n```json\n{\n    \"status\": \"error\",\n    \"message\": \"Invalid or non-existent JSON file: 'data.json'\",\n    \"error_code\": \"invalid_or_nonexistent_json_file\"\n}\n```\n\n## Development\n\nIf you want to build and collaborate on the project, follow these steps to set up your development environment.\n\n### 1. Setting Up the Virtual Environment\n\nFirst, create the virtual environment:\n\n```bash\nmake venv\n```\n\n### 2. Installing Dependencies\n\nFirst, make sure to activate the virtual environment:\n\n```bash\nsource venv/bin/activate\n```\n\nThen, install the development dependencies listed in the `requirements-dev.txt` file:\n\n```bash\nmake install-deps\n```\n\nThe `requirements-dev.txt` file includes:\n\n-   [pytest](https://github.com/pytest-dev/pytest)\n-   [pytest-cov](https://github.com/pytest-dev/pytest-cov)\n-   [coverage](https://github.com/nedbat/coveragepy)\n\n### 3. Running tests\n\nTo run tests using `pytest`:\n\n```bash\nmake test\n```\n\nTo run tests using `unittest`:\n\n```bash\nmake test-unittest\n```\n\n### 4. Generating Coverage Reports\n\nTo run coverage tests and generate a report:\n\n```bash\nmake coverage\n```\n\nTo generate an HTML coverage report:\n\n```bash\nmake coverage-report\n```\n\n### 5. Building\n\nTo build the binary file:\n\n```bash\nmake build\n```\n\n### 6. Cleaning Up\n\nFirst, exit the virtual environment:\n\n```bash\ndeactivate\n```\n\nThen clean up the virtual environment and coverage files\n\n```bash\nmake clean\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/lucianoayres/rjip/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucianoayres%2Frjip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucianoayres%2Frjip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucianoayres%2Frjip/lists"}