add parameter immutable to some graph operations in sage/graphs/generic_graph.py

[dcoudert]

As proposed in #39177, we add parameter immutable to (some) graph operations.

• add tests to add_clique, add_path, and add_cycle to prevent modifying an immutable graph
• add the parameter to method complement
• ensure that method to_undirected behaves as expected
• propose a more direct version of disjoint_union to ensure a correct behavior
• ensure that method union behaves as expected

This is only a beginning. More to come in future PRs.

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

⌛ Dependencies

[github-actions]

Documentation preview for this PR (built with commit f75189b; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[mantepse]

I must say that I would like it much better if graphs were immutable by default :-(

[dcoudert]

Before debating such drastic change, we must make sure that the entire graph library, including generators, is consistent.

[fchapoton]

maybe you could create a function "scream_if_immutable" to avoid repeating ?

[fchapoton]

missing backtick

[dcoudert]

done (3 times).

[dcoudert]

maybe you could create a function "scream_if_immutable" to avoid repeating ?

I'm adding this idea to my todo list. It should certainly be done also in backends...