{"id":16870427,"url":"https://github.com/narimiran/scopy","last_synced_at":"2026-03-01T04:36:18.428Z","repository":{"id":115375793,"uuid":"96697921","full_name":"narimiran/scopy","owner":"narimiran","description":"Python script for searching through your digital books and cataloguing them in an easy-to-share list of files.","archived":false,"fork":false,"pushed_at":"2019-12-10T03:46:30.000Z","size":6,"stargazers_count":31,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-11-16T05:03:32.879Z","etag":null,"topics":["catalog","cataloguing","cli","command-line","epub","mobi","pdf","python","python3"],"latest_commit_sha":null,"homepage":null,"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/narimiran.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null}},"created_at":"2017-07-09T16:50:18.000Z","updated_at":"2024-06-25T22:04:44.000Z","dependencies_parsed_at":"2023-03-10T03:00:23.543Z","dependency_job_id":null,"html_url":"https://github.com/narimiran/scopy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/narimiran/scopy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narimiran%2Fscopy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narimiran%2Fscopy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narimiran%2Fscopy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narimiran%2Fscopy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/narimiran","download_url":"https://codeload.github.com/narimiran/scopy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narimiran%2Fscopy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29960253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T01:47:18.291Z","status":"online","status_checked_at":"2026-03-01T02:00:07.437Z","response_time":124,"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":["catalog","cataloguing","cli","command-line","epub","mobi","pdf","python","python3"],"created_at":"2024-10-13T15:04:19.714Z","updated_at":"2026-03-01T04:36:18.084Z","avatar_url":"https://github.com/narimiran.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Scopy\n\nPython script for searching through your digital books and cataloguing them in an easy-to-share list of files.\n\n\u0026nbsp;\n\n## How To Use\n\n### Basic usage:\n\n```bash\n$ python scopy.py\n```\nSearches current folder and all its subfolders for .epub, .mobi, and .pdf files. Outputs the results to the console:\n\n```\nFilename:                                          Ext:     Size:    Relative path:\nEpub In First Sub                                  .epub    515  B   /first_subdirectory\nEpub In Second Sub                                 .epub      3 KB   /second_subdirectory\nMobi In First Sub                                  .mobi      2 KB   /first_subdirectory\nPdf In Dir                                         .pdf      63 KB\nPdf In Second Sub                                  .pdf       1 KB   /second_subdirectory\n```\n\nIf you want to save the results in the easy to share file, provide the `--outfile` (`-o`) argument:\n\n```bash\n$ python scopy.py -o my_books.txt\n```\n---\n\nThe list of all options can be seen by calling `help` with:\n```bash\n$ python scopy.py -h\n```\n\n```\nusage: scopy.py [-h] [-d DIR] [-e [EXT [EXT ...]]] [-c] [-f [F [F ...]]]\n                [-m N] [-i [DIR [DIR ...]]] [-r] [-s [S [S ...]]] [-z] [-v]\n                [-o FILE]\n\nCatalogue your digital books (and more)\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -d DIR, --directory DIR\n                        Path to the directory you want to scan. Default:\n                        current directory\n  -e [EXT [EXT ...]], --ext [EXT [EXT ...]]\n                        Choose wanted file extensions. Default: ['pdf',\n                        'epub', 'mobi']\n  -c, --current         Scan just the current directory, without subfolders.\n                        Default: False\n  -f [F [F ...]], --filter [F [F ...]]\n                        Filter results to include only the filenames\n                        containing these words. Default: None\n  -m N, --minsize N     Include only the files larger than the provided size\n                        (in bytes). Can use suffixes `k`, `m`, and `g` for\n                        kilo-, mega-, and giga-bytes. For example: 64k.\n                        Default: 0\n  -i [DIR [DIR ...]], --ignore [DIR [DIR ...]]\n                        Ignores subdirectories containing these words.\n                        Default: None\n  -r, --raw             Keep the original filenames, don't change to Title\n                        Case, and don't replace symbols such as -, _, +, etc.\n                        Default: False\n  -s [S [S ...]], --sort [S [S ...]]\n                        Sort files by: [n]ame, [e]xtension, [s]ize,\n                        [d]irectory, or their combination. Default: by Name\n  -z, --descending      Sort file descending: from Z to A, from larger to\n                        smaller. Default: False\n  -v, --verbose         Output summary statistics at the top. Default: False\n  -o FILE, --outfile FILE\n                        Choose an output file to save the results. Default:\n                        None, prints to console\n```\n\n\n### More examples\n\n```bash\n$ python scopy.py -e pdf -i first\n```\nSearches current folder and all its subfolders for files with `.pdf` extension (`-e`), ignoring subdirectories (`-i`) containing the word `first`:\n\n```\nFilename:                                          Ext:     Size:    Relative path:\nPdf In Dir                                         .pdf      63 KB\nPdf In Second Sub                                  .pdf       1 KB   /second_subdirectory\n```\n\n---\n\n```bash\n$ python scopy.py -f sub -s d e n -r -v\n```\nFilter (`-f`) the results to only the filenames including the word `sub`, sort by (`-s`) directory (`d`), then extension (`e`), then name (`n`). Keep raw (`-r`) filenames (without Title Case and without replacing symbols). Make verbose (`-v`) output:\n\n```\nScanned directory:                  [absolute path]/scopy/scopy_example\nLooking for files containing:       sub\nWith extensions:                    .epub, .pdf, .mobi\nFound:                              4 files\n\n\nFilename:                                          Ext:     Size:    Relative path:\nepub_in_first_sub                                  .epub    515  B   /first_subdirectory\nmobi_in_first_sub                                  .mobi      2 KB   /first_subdirectory\nepub_in_second_sub                                 .epub      3 KB   /second_subdirectory\npdf_in_second_sub                                  .pdf       1 KB   /second_subdirectory\n```\n\n---\n\n```bash\n$ python scopy.py -d D:/Documents/Books -c -o book_list.txt\n```\n\nScan `D:/Documents/Books` folder (both absolute and relative paths can be used), without subfolders (`-c`), and save the results in the output file (`-o`) called `book_list.txt`.\n\n\u0026nbsp;\n\n## Installation\n\n### Requirements\n\nPython 3.4+\n\nNo other dependencies.\n\n### Install\n\nClone this repo:\n```bash\ngit clone https://github.com/narimiran/scopy.git\n```\nor just manually download the file [`scopy.py`](scopy.py).\n\n\u0026nbsp;\n\n## FAQ\n\n\u003e Why the name Scopy?\n\nFrom the Greek verb σκοπέω (skopéō), meaning \"I search\". The suffix `py` is, of course, because of Python.\n\n\u003e Can't I just use X or Y, to get the same (or better) result?\n\nYou probably can. Scopy was done as a fun weekend project to practice my Python skills. It wasn't meant to be groundbreaking.\n\n\u003e Is there really a limit to search only for digital books? Can't I just search for any extension?\n\nScopy was started because I wanted to catalogue my .pdf collection, but as you figured it out - it can be used to search any format you like.\n\n\u0026nbsp;\n\n## License\n\nMIT License.  \nSee the details at [LICENSE](/LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarimiran%2Fscopy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnarimiran%2Fscopy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarimiran%2Fscopy/lists"}