{"id":37099683,"url":"https://github.com/plangrid/pdf-annotate","last_synced_at":"2026-01-14T12:09:40.286Z","repository":{"id":49870997,"uuid":"141054667","full_name":"plangrid/pdf-annotate","owner":"plangrid","description":"Pure-python library for adding annotations to PDFs","archived":true,"fork":false,"pushed_at":"2021-03-29T17:10:47.000Z","size":10559,"stargazers_count":206,"open_issues_count":23,"forks_count":44,"subscribers_count":181,"default_branch":"master","last_synced_at":"2025-09-23T14:55:14.915Z","etag":null,"topics":["heraignore","library"],"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/plangrid.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}},"created_at":"2018-07-15T19:59:09.000Z","updated_at":"2025-08-17T12:31:32.000Z","dependencies_parsed_at":"2022-09-10T08:01:09.546Z","dependency_job_id":null,"html_url":"https://github.com/plangrid/pdf-annotate","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/plangrid/pdf-annotate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plangrid%2Fpdf-annotate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plangrid%2Fpdf-annotate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plangrid%2Fpdf-annotate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plangrid%2Fpdf-annotate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plangrid","download_url":"https://codeload.github.com/plangrid/pdf-annotate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plangrid%2Fpdf-annotate/sbom","scorecard":{"id":736970,"data":{"date":"2025-08-11","repo":{"name":"github.com/plangrid/pdf-annotate","commit":"e78638d71f156ed79e8384e3bac54d638136211c"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.8,"checks":[{"name":"Maintained","score":0,"reason":"project is archived","details":["Warn: Repository is archived."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":10,"reason":"all changesets reviewed","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/pullrequests.yml:1","Warn: no topLevel permission defined: .github/workflows/tag.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/pullrequests.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/plangrid/pdf-annotate/pullrequests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/pullrequests.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/plangrid/pdf-annotate/pullrequests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tag.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/plangrid/pdf-annotate/tag.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tag.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/plangrid/pdf-annotate/tag.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tag.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/plangrid/pdf-annotate/tag.yml/master?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/pullrequests.yml:27","Warn: pipCommand not pinned by hash: .github/workflows/pullrequests.yml:28","Warn: pipCommand not pinned by hash: .github/workflows/tag.yml:19","Info:   0 out of   4 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned","Info:   0 out of   3 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-22T16:09:45.276Z","repository_id":49870997,"created_at":"2025-08-22T16:09:45.276Z","updated_at":"2025-08-22T16:09:45.276Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28419527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["heraignore","library"],"created_at":"2026-01-14T12:09:39.545Z","updated_at":"2026-01-14T12:09:40.277Z","avatar_url":"https://github.com/plangrid.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pdf-annotate\nA pure-python library to add annotations to PDFs.\n\n[![Build Status](https://travis-ci.com/plangrid/pdf-annotate.svg?branch=master)](https://travis-ci.com/plangrid/pdf-annotate)\n\n## About\npdf-annotate is a simple library to add PDF annotations to PDFs. Under the hood\nit uses the powerful and unopinionated `pdfrw` library to parse the PDF to\nfigure out where to place the annotations.\n\n## Usage\n```python\nfrom pdf_annotate import PdfAnnotator, Location, Appearance\na = PdfAnnotator('a.pdf')\na.add_annotation(\n    'square',\n    Location(x1=50, y1=50, x2=100, y2=100, page=0),\n    Appearance(stroke_color=(1, 0, 0), stroke_width=5),\n)\na.write('b.pdf')  # or use overwrite=True if you feel lucky\n```\n### Annotation Types\n`pdf-annotate` includes most of the basic PDF annotation types, leaving out some\nof the more complex interactive types. Contributions for these welcome! Currently supported\nannotation types are:\n\n* square\n* circle\n* line\n* polygon\n* polyline\n* ink\n* text\n* image\n\n### Appearance\nAnnotations' appearance is controlled by the `Appearance` class, passed to the\n`appearance` argument to `add_annotation`. Not all attributes\non this class apply to all annotations; documentation on this is forthcoming.\n\n### Location\nWhere an annotation is placed on the PDF is controlled by the `Location` class, passed\nto the `location` argument to `add_annotation`. By default these coordinates are in the\nPDF's user space scale, which is \"points\". There are 72 points/inch, so an 8.5\"x11\" PDF\nwould have a coordinate system of 612x792. See [scaling and rotation](#scaling-and-rotation) below\nfor changing the coordinate system.\n\nAnnotations that are defined by width/height\n(square, circle, text, image) require `x1`, `y1`, `x2`, `y2` attributes, while annotations\nthat are defined by a list of points (line, polygon, polyline, ink) require a `points` attribute.\nAll annotations require a `page` attribute, which determines which page of the PDF the\nannotations will be placed on.\n\n### Metadata\nPDF annotations can contain arbitrary metadata. This is controlled by the `Metadata` class,\npassed to the `metadata` argument to `add_annotation`. By default, annotations will contain\ndefault values for creation date, modification date, unique name (just a uuid), and the print flag\nset. To leave off any of these, use the `UNSET` singleton. For more context, check out the\n[`Metadata`](https://github.com/plangrid/pdf-annotate/blob/a59e1554f6bb912087932d1c0c4f3524524309fa/pdf_annotate/config/metadata.py#L43)\nclass itself.\n\n### Scaling and rotation\n`pdf-annotate` draws annotations as though you were drawing them in a PDF viewer,\nmeaning it assumes you want to draw on the rotated page. For example an annotation drawn at\n(10, 10) on a 90° rotated page will still appear in the bottom left, not the top-left.\n\nIt also supports specifying your annotations' coordinates in differently scaled coordinate systems.\nIf, for example, you know your coordinates are in the system of the PDF rastered at 150 DPI, you\nwould specify `scale=72.0/150` in the constructor to properly scale your coordinates to PDF user space.\n\nFinally, if all you have is the dimensions of each page in the viewer's coordinate system, you can\nspecify these. Building on the previous example, if you know the dimensions of page 0, you would use\n```python\na = PdfAnnotator('a.pdf')\na.set_page_dimensions((1275, 1650), 0)\n```\nNote that these are the dimensions of an un-rotated 8.5\"x11\" page rastered at 150 DPI. If the same page is\nrotated 90° or 270°, you would pass in `(1650, 1275)`.\nSetting page dimensions specifically overrides document-wide scale and rotation settings.\n\n## Advanced Usage\n\n### Using the Content Stream\n`pdf-annotate` also includes an abstraction of the PDF content stream that you can use to\ndraw arbitrary annotation shapes onto the PDF. To fully take advantage of this feature, we\nrecommend reading the relevant parts of the [PDF specification](https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf):\n(Section 8 - Graphics and Section 12.5.5 - Annotation Appearance Streams).\n\nTo use an explicit content stream in an annotation, specify the `appearance_stream`\nargument to the `Appearance` object as a `pdf_annotate.graphics.ContentStream` object.\nSee the [end-to-end tests](https://github.com/plangrid/pdf-annotate/blob/a59e1554f6bb912087932d1c0c4f3524524309fa/tests/end_to_end/test_annotate_pdf.py#L317)\nfor examples.\n\n## Local Development\nTests are run against several supported python versions using `tox`. To get this to\nwork, you need versioned python executables - e.g. `python3.6` - in your path.\n\nAn opinionated setup, which assumes you have certain python versions installed,\nand that you use `pyenv`, is provided by `make setup`. After this you can run\n`tox` to run tests.\n\n### Manual tests\nFully automated testing is difficult for things that depend on the complexities\nof PDF viewers. When making changes, it's good practice to compare the file\n`tests/end_to_end/pdfs/end_to_end.pdf`, which is generated during testing,\nwith `expected.pdf` in the same directory. To ensure rotation is handled correctly,\nthere is also `end_to_end_rotated_90.pdf` and corresponding expected file.\n\nBy default, the file will be the one generated during the last python version's `tox` run.\nTo check a specific version, use e.g. `tox -e py36`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplangrid%2Fpdf-annotate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplangrid%2Fpdf-annotate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplangrid%2Fpdf-annotate/lists"}