{"id":17930539,"url":"https://github.com/lovasoa/pagelabels-py","last_synced_at":"2025-05-12T14:32:36.711Z","repository":{"id":46158687,"uuid":"52787676","full_name":"lovasoa/pagelabels-py","owner":"lovasoa","description":"Python library to manipulate PDF page labels","archived":false,"fork":false,"pushed_at":"2024-08-03T11:41:42.000Z","size":49,"stargazers_count":74,"open_issues_count":1,"forks_count":12,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-15T20:03:34.048Z","etag":null,"topics":["labels","page","pdf","pdf-document-processor"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pagelabels/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lovasoa.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":"2016-02-29T11:56:31.000Z","updated_at":"2025-02-21T12:58:56.000Z","dependencies_parsed_at":"2025-01-26T03:01:11.712Z","dependency_job_id":"ddbc3f4e-8196-4c2b-a836-cba5be097fde","html_url":"https://github.com/lovasoa/pagelabels-py","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovasoa%2Fpagelabels-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovasoa%2Fpagelabels-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovasoa%2Fpagelabels-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovasoa%2Fpagelabels-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lovasoa","download_url":"https://codeload.github.com/lovasoa/pagelabels-py/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754967,"owners_count":21958934,"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":["labels","page","pdf","pdf-document-processor"],"created_at":"2024-10-28T21:14:02.149Z","updated_at":"2025-05-12T14:32:36.663Z","avatar_url":"https://github.com/lovasoa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pagelabels\nPython utility to manipulate PDF page labels.\n\nA useful but rarely-used feature of PDFs is the ability to use\ncustom naming schemes for pages. This allows to start a PDF at\nany given page number instead of 1, to restart page numbering \nfor each section of a long PDF, or to attribute a certain name\nto a given page.\n\n![Example page labels generated with pagelabels and viewed in evince](https://user-images.githubusercontent.com/552629/48559767-88368380-e8ec-11e8-827c-068c1d34c588.png)\n\n## Addpagelabels utility\nPDF files can contain one ore more page numbering schemes.\nEach scheme has a start page, specifying the page where it should take\neffect. All subsequent pages will be affected by the scheme,\nuntil another page numbering scheme is encountered.\nThis utility allows adding, removing, and updating page numbering schemes\nin a PDF file.\n\n### Installation\n#### Dependencies\n\nInstall **pip** if you don't have it already:\n##### On Linux\n```bash\n$ sudo apt install python3-pip\n```\n\n##### On MacOS\nInstall [brew](https://brew.sh/), and then install python:\n\n```bash\nbrew install python\n```\n\n##### On Windows\nInstall [WSL](https://docs.microsoft.com/en-us/windows/wsl/about)\nand then follow the linux instructions.\n\n#### The script\nInstall **pagelabels-py** :\n```\npython3 -m pip install --user --upgrade pagelabels \n```\n\n### How to use\n\n#### Add a new page index to the PDF\nThis reads the file `/tmp/test.pdf`,\nand creates a copy of it with new page labels\nwithout deleting the ones that may already exist.\nThe new index will take effect from the 1st page of the PDF,\nwill be composed of uppercase roman numerals, preceded by the string \"Intro \",\nand starting from \"V\".\n\nPage numbers will be: \"Intro V\", \"Intro VI\", \"Intro VII\", ...\n```\npython3 -m pagelabels --startpage 1 --type \"roman uppercase\" --prefix \"Intro \" --firstpagenum 5 --outfile /tmp/new.pdf /tmp/test.pdf\n```\n\n#### Print usage info\n```\npython3 -m pagelabels -h\n```\n\nThis should print:\n```\nusage: pagelabels [-h] [--outfile out.pdf] [--delete | --update]\n                  [--startpage STARTPAGE]\n                  [--type {arabic,roman lowercase,roman uppercase,letters lowercase,letters uppercase,none}]\n                  [--prefix PREFIX] [--firstpagenum FIRSTPAGENUM]\n                  [--load other.pdf]\n                  file.pdf\n\nAdd page labels to a PDF file\n\npositional arguments:\n  file.pdf              the PDF file to edit\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --outfile out.pdf, -o out.pdf\n                        Where to write the output file\n  --delete              delete the existing page labels\n  --update              change all the existing page numbering schemes instead\n                        of adding a new one\n  --startpage STARTPAGE, -s STARTPAGE\n                        the index (starting from 1) of the page of the PDF\n                        where the labels will start\n  --type {arabic,roman lowercase,roman uppercase,letters lowercase,letters uppercase,none}, -t {arabic,roman lowercase,roman uppercase,letters lowercase,letters uppercase,none}\n                        type of numbers: arabic = 1, 2, 3, roman = i, ii, iii,\n                        iv, letters = a, b, c, none =  (number is empty)\n  --prefix PREFIX, -p PREFIX\n                        prefix to the page labels\n  --firstpagenum FIRSTPAGENUM, -f FIRSTPAGENUM\n                        number to attribute to the first page of this index\n  --load other.pdf      copy page number information from the given PDF file\n```\n\n#### Delete existing page labels from a PDF\n```\npython3 -m pagelabels --delete file.pdf\n```\n\n#### Copy page labels from one PDF to another\nThe following will take the page labelling scheme from `source.pdf` and \napply it to `target.pdf` :\n```\npython3 -m pagelabels --load source.pdf target.pdf\n```\n\n### Complete example: creating a PDF with several different page numbering styles\nLet's say we have a PDF named `my_document.pdf`, that has 12 pages.\n * Pages 1 to 4 should be labelled `Intro I` to `Intro IV`.\n * Pages 5 to 9 should be labelled `2` to `6`.\n * Pages 10 to 12 should be labelled `Appendix A` to `Appendix C`.\n\nWe can issue the following list of commands:\n\n```bash\npython3 -m pagelabels --delete \"my_document.pdf\"\npython3 -m pagelabels --startpage 1 --prefix \"Intro \" --type \"roman uppercase\" \"my_document.pdf\"\npython3 -m pagelabels --startpage 5 --firstpagenum 2 \"my_document.pdf\"\npython3 -m pagelabels --startpage 10 --prefix \"Appendix \" --type \"letters uppercase\" \"my_document.pdf\"\n```\n\n### Updating existing page numbers\nLet's say we have a PDF with pages named 10, 11, 12, A, B, C\nand we want to add a prefix to the labels, while keeping the existing custom\npage offset and styles. We can do that using the `--update` option of pagelabels:\n\n```\npython3 -m pagelabels --update --prefix \"EX-\" my_document.pdf\n```\n\nThis will update the existing labels to EX-10, EX-11, EX-12, EX-A, EX-B, EX-C.\n\n## Warning\n*pagelabels-py* internally uses [pdfrw](https://github.com/pmaupin/pdfrw), that can write only [**PDF version 1.3**](https://en.wikipedia.org/wiki/History_of_the_Portable_Document_Format_(PDF)). If your PDF uses features that are not compatible with PDF 1.3, you may see it not being rendered correctly after using *pagelabels-py*.\n\n## Usage as a python library\nThis project can be used as a python library.\nSee [*pagelabels* on the python package index](https://pypi.org/project/pagelabels/).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flovasoa%2Fpagelabels-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flovasoa%2Fpagelabels-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flovasoa%2Fpagelabels-py/lists"}