Hyperlinks -- IMPLEMENTED

[chapmanwilliam]

It would be useful to be able to tag a hyperlink with a name string. You can do this for annotations by setting annot.info['name']="Desired Name".

In this way, I would like a) to be able to identify links created by me rather than existing links created by someone else b) so I can delete my links and not somebody else's.

Is that possible please?

William

[JorjMcKie]

Annotations and widgets are automatically assigned a unique (per page) name upon creation. I have to check for links - will be added if I forgot those.
The terminus technicus for these names is "id" and has the PDF key /NM. This is part of the annot.info dictionary under the key "id".

[JorjMcKie]

The annotation name is reserved for other purposes: mostly the icon name. Shouldn't be abused for private identification purposes.
The /NM PDF key is what you are looking for. It is autogenerated by PyMuPDF according to the schemes fitzannot-nnn, fitzwidget-nnn and (to be added) fitzlink-nnn. The number suffixes are chosen such that the result is unique.

[JorjMcKie]

...will be added if I forgot those.

Done. The dictionaries in page.getLinks() or yielded by page.links() will now have an "id" key of the described format. As for annotations and fields, it is autogenerated such that page.insertLink() and page.updateLink() will always add a /NM property to the link.

[chapmanwilliam]

That's good Jorj. But I don't think it solves me problem of being able to identify links I have created, as distinguished from links that may already exist in the file. For example, I may want to be able to colour links I have created, or delete them. Is there a way to do this?

[JorjMcKie]

The only available PDF key for this type of thing is /NM. This property must be unique among all annotations, links and fields for a page.
This implies that some type of string "stemming" must be used.
For certain internal reasons, I am also dependent on that these three type have different stems.
I also do not want do add a new parameter to dozens of methods for this purpose.
So to wrap up, the following should be possible:

1. A new method that sets a "global stem" for annotations, fields and links, e.g. "Chapman": fitz.set_annot_stem("Chapman") or fitz.TOOLS.set_annot_stem("Chapman"). Default is "fitz".
2. Insertions or updates of annotations, fields and links pick up that global stem and build ids with the following patterns "Chapman-Annn", "Chapman-Wnnn", and "Chapman-Lnnn" respectively with a number nnn chosen such that the whole thing is unique.

[JorjMcKie]

Wheel generation for the revised code is underway. Give half an hour time or so.
What it contains addressing your requirements:

1. Link personalization: Use fitz.TOOLS.set_annot_stem(name) to globally define a prefix to be used when creating a link, annotation or field. The generated PDF key is /NM and always looks like name-Lnnn (example for a link). To find the links inserted using this prefix, a code snippet like this one could be used:

mylinks = [lnk for lnk in page.getLinks() if lnk["id"].startswith(name)]

2. Setting font properties for the selected table of contents items:

toc = doc.get_toc(False)  # important: use the full TOC
idx = n  # the index of the toc entry in that list
d = toc[idx][3]  # the destination dictionary of the toc entry
d["color"] = (0,0,1)  # blue - always use PDF color 3-tuples!
d["bold"] = True
d["italic"] = True
d["collapse"] = False  # whether to collapse/expand sub-items
doc.set_toc_item(idx, dest_dict=d]  # the only valid call pattern in this case

3. Page labels: writing back page label patterns to the document should now work.

[JorjMcKie]

Here an example for coloring a toc item:

>>> doc=fitz.open("pillow.pdf")
>>> toc=doc.get_toc(False)
>>> for i, item in enumerate(toc):
	if item[:2] == [1, "Porting"]:  # the item we want to color
		break
>>> d = toc[i][3]
>>> d["color"] = (0,0,1)
>>> d["bold"] = True
>>> d["italic"] = True
>>> doc.set_toc_item(i,dest_dict=d)
>>> doc.save("x.pdf")
>>> 

Before:

After:

Both times using Adobe Acrobat.

[JorjMcKie]

The item search could be more elegantly formulated using a list comprehension:

found_items = [i for i, item in enumerate(toc) if item[:2] == [1, "Porting"]]
idx = found_items[0]  # the item index
# also to be used if searching for several similar items

This also has a much better performance.

[JorjMcKie]

Some more on coloring TOC items:
I am almost sure to use the extended TOC format for returning item colors. There are some issues to sort out:

• TOC generation works for all document types, therefore I need a second pass through already extracted items to enrich their information.
• Compared to doc.get_toc(True) (the simple format), doc.get_toc(False) (today's complete format) is about 10 times slower:
  • The Adobe manual has 794 toc items.
  • the simple format requires 4.2 milliseconds
  • the extended format needs about 42 milliseconds
• Another pass through all the items would of course add to the 42 ms of the extended format. Let's say a ballpark number of another 20 to 30 ms. The info lookup is not the issue here, but updating the Python destination dictionary of each item will be time consuming.
• I therefore think, a better solution would be to let the programmer request this enrichment for each item of interest - roughly along this line doc.complete_toc_item(toc, idx). An additional toc parameter is required here, that must have been created with doc.get_toc(False).
• Or I invent a second option value doc.get_toc(simple=...). Today we have 1=True, 0=False (extended). We could add value -1 or 2 for "super-extended".

[JorjMcKie]

Have good news for you wrt TOC item colors:
I wrote a function in C that walks through an extended TOC list and completes each item's dictionary with color information (and more). To my surprise, this function is very fast: it slows down doc.get_toc(False) by only 1% or so.
So it is no performance problem to always invoke it under the hood (for PDFs only of course), if an extended TOC is requested.

This means for yur requirement:

1. For every item of doc.get_toc(False) the last entry is a dictionary with the following additional keys:
   • xref: the xref of the item (always present, zero if no PDF)
   • color: a PDF color triple (red, green, blue) or omitted
   • bold: either True or omitted
   • italic: either True or omitted
   • collapse: either True or omitted

[chapmanwilliam]

That's excellent Jorj, thank you very much.

Is there a new wheel I should be installing?

[JorjMcKie]

Is there a new wheel I should be installing?

yes, absolutely!