Feature suggestion: provide pdfrw examples as commands

[Lucas-C]

Explanation

pdfrw provides a set of very useful scripts: https://github.com/sarnold/pdfrw/tree/master/examples
Personnally, I very often use:

• cat.py to concatenate/merge multiple PDFs
• subset.py to extract some pages from a PDF

I think that a script to extract all images from a PDF would also be handy, like this one: https://stackoverflow.com/a/34116472/636849

The idea would be for py-pdf to expose similar features as simple CLI console_scripts:
https://github.com/Lucas-C/pre-commit-hooks/blob/master/setup.py#L27

This way, a user could simply:

pip install pypdf
pypdf_subset in.pdf 31-34 [out.pdf]
pypdf_cat in.pdf out.pdf merged.pdf
pypdf_extract_images merged.pdf

Would you be open to welcome such feature in py-pdf?

[stefan6419846]

I am not sure if I like the idea of "spamming tons of entries" into the local $PATH, especially considering global installations or larger projects with lots of dependencies. Personally, I prefer one main entry point per package (exposed through a dedicated console_scripts entry point and through __main__.py) with subcommands and maybe a simple API for library usage.

[Lucas-C]

I am not sure if I like the idea of "spamming tons of entries" into the local $PATH, especially considering global installations or larger projects with lots of dependencies. Personally, I prefer one main entry point per package (exposed through a dedicated console_scripts entry point and through __main__.py) with subcommands and maybe a simple API for library usage.

Agreed!
The we could have this:

pip install pypdf
pypdf subset in.pdf 31-34 [out.pdf]
pypdf cat in.pdf out.pdf merged.pdf
pypdf extract-images merged.pdf

[pubpub-zz]

I have no strong opinion : I'm using pypdf as a library not in command line. What is proposed sounds reasonable but I would not like to see people asking for new commands, and loose some time/spam the issues database with problems linked with use of the tools in the environment (windows Linux Mac to be properly managed and tested).

[pubpub-zz]

a proposal : add a pool with all alternatives in questions and observe the results after a month

[Lucas-C]

a proposal : add a pool with all alternatives in questions and observe the results after a month

I dot have your extended experience with the py-pdf community:
if you feel that this is the good approach regarding the choice of features to adopt in py-pdf, I'm all in! 😊

[pubpub-zz]

if you feel that this is the good approach regarding the choice of features to adopt in py-pdf, I'm all in! 😊

I'm just a poor bug killer that's all😳
but I think it worth it.

[Lucas-C]

I'll let you organize this poll 🙂

In the meantime, I submitted a draft PR to implement this: #2170

[pubpub-zz]

poll is open in #2172
@MartinThoma can you promote the discussion welcome ?

[MasterOdin]

There is already https://github.com/py-pdf/pdfly which provides what you're looking for I think?

[MartinThoma]

I completely agree that this project lacks documentation. I think of 4 kinds:

1. ReadTheDocs with a user guide giving concrete examples. I think I can set that up over the weekend.
2. StackOverflow / Superuser: there are certainly several questions going into that direction
3. External sites: YouTube / Medium / Twitter ... I can get started with Medium. I almost have no followers on Twitter, but I can add some examples once in a while via https://twitter.com/py_pdf

[MartinThoma]

1. Readthedocs is integrated: https://pdfly.readthedocs.io/ (CI builds it automatically + first few pages + linked from README)
2. Superuser: 1, 2 added
3. Twitter: 1

[MasterOdin]

I think that would be good to also have pypdf cross-link to pdfly directly, so that people hitting pypdf as a way to manipulate PDFs should hopefully see the link to pdfly.

Additionally, I think if trying to blow up pdfly, it would be good to update the repo description for pdfly to something that mentions CLI, as right now "Python code examples how to interact with PDF files" doesn't say that.

[MartinThoma]

Good points!

CLI tool to extract (meta)data from PDF and manipulate PDF files is better, but there still is quite a bit of room for improvement 🤔 I'm open for suggestions :-)

[MartinThoma]

#2184

[Lucas-C]

By the way, while developping PR #2170 I spotted 2 potential bugs:
#2170 (comment)