Add new selenium 4 print page as PDF functionality

[emanlove]

Selenium 4 provides a new method for printing out the page as a PDF. We want to implement within SeleniumLibrary this functionality.

[emanlove]

Some of my initial notes on Print a page as a PDF

• Is there different output formats (like screenshots which can come as png, raw data, etc)? (And should we match the specification of the output to other library keywords like screenshot?)
• There are print options. How shall we supply those?
• Some print options are like left margin, right margin but these have no units. What are the unit(s)? Can they be different units like cm verus inches? And if so are there any similar keywords within the ecosystem that have units - like timestamps that we should match to?

Reference: https://www.w3.org/TR/webdriver/#print-page

[SamMaksymyshyn]

May I put some draft ideas on your initial notes?

There are print options. How shall we supply those?

There is a limited set of options at the moment, so one of the options could be to specify all of them as arguments to the printing keyword.

What are the unit(s)? It seems the reference says (18.1 item 23) that it is centimeters.

IMHO, an argument like ${units}=cm could be added. And in case of inch-value passed, -> all passed numeric arguments could be recalculated.

And probably an additional parameter like ${pdf_filename} could be passed to specify what file and where should be created.

E.g. proto idea expressed in RF syntax

** Keywords ***
print page to pdf
	[Arguments]
	 ...  ${path_to_file}
	 ...  ${background}=${None}
	 ...  ${margin_bottom}=${None}  ${margin_left}=${None}   ${margin_right}=${None}   ${margin_top}=${None}
	 ...  ${orientation}=${None}
	 ...  ${page_height}=${None}   ${page_ranges}=${None}   ${page_width}=${None}
	 ...  ${scale}=${None}
	 ...  ${shrink_to_fit}=${None}
	 ...  ${units}=cm  #  cm or inches

    ${print_options} =        evaluate  selenium.webdriver.common.print_page_options.PrintOptions()
    IF  $units.lower() in ['inch', 'inches']
    	${margin_bottom} =  evaluate  float($margin_bottom) * 2.54 if $margin_bottom is not None else None
    	# etc ...
    END

    IF  $scale is not None
        ${print_options.scale}   Convert To Number   ${scale}
    END
    IF  $orientation is not None
        ${print_options.orientation}   Set Variable  ${orientation}
    END
    # ... etc for other arguments

    ${webdriver} =            get library instance    SeleniumLibrary
    ${pdf_content_encoded} =  call method  ${webdriver.driver}   print_page  ${print_options}
	${decoded_content} =      evaluate  base64.b64decode($pdf_content_encoded)    modules=base64
    create binary file        ${path_to_file}     ${decoded_content}

[emanlove]

Yes, your thoughts on implementation design are very much welcomed. To me the initial design was similar in that one could provide these as arguments when printing. But this also raises a few clarifying questions ..

If one has to do multiple print pages, is there an easier or less verbose way then just repeating the same arguments over and over again?
Could the options all be provided as a single data structure as the first argument instead of, in your example, path_to_file?
Should/Could we make these options as sticky? That is set them once and then they will be used again unless changed. This would mean we would need setter and getter keywords, I believe, and then are we just adding more to the total library count of keywords (is this bad or good)?

In addition I would like to allow for flexibility within the filename to use a marker. That is {index} or as #1840 does allow for other markers like {timestamp} or possibly {page_title} for this print functionality. That can be added in later releases but something I was keeping in mind.

[emanlove]

A couple more notes ..

At this time it looks like the only unit one can use (directly) on the API is centimeters/cm. When UI first looked at the Print Page As PDF methods within Python Selenium I didn't see any units and wandered if this was a possibility. Reading the current revision of the webdriver spec it looks like all sizes are within cm. We could of course add some convenience functionality where we allow other units and convert ourselves. Or even allow for a descriptive paper size; for example "A4" or "Legal". I would recommend for the first version to not include units as an option and see how end users use this and might want more functionality.

The other item is minimum options needed for printing. In first investigating this functionality I found that if the one used an empty print_page_options class (which does not set any default values on initialization) then nothing gets printed. Nor does the webdriver call throw an error. I don't know if this is a selenium python implementation error, oversight, or something else but I could see this changing. Either way we might need to force defaults on some of these options.

[emanlove]

Added in #1851