Closed hakandilek closed 1 month ago
Foremost, thanks for reporting the incorrect docs. Feel free to pullrequest improvements. The doc-sources are here: https://github.com/CycloneDX/cyclonedx-python-lib/tree/main/docs
in https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/examples/complex_serialize.py we use the following options:
both examples correlate with yours.
Which one of 🅰️ or 🅱️ would be the preferred way?
We do not have one.
But we have one for certain situations:
output_format
and schema_version
, then go with the flexible 🅰️. - here you can inject your variables.output_format
and schema_version
are mere constants, then you could use the less flexible 🅱️.For example, let's say I had a script that always outputs CycloneDX 1.5 as XML - then I would go with 🅱️.
If I had a CLI tool that takes the output_format
and schema_version
from command line arguments, then I would go with 🅰️, since it gives me more flexibility without writing large behavior-maps or if
/elif
/match
/case
code blocks.
Let's also look at the internals.
🅰️'s make_outputter
is just a fancy wrapper with a maintained behavior map for 🅱️. https://github.com/CycloneDX/cyclonedx-python-lib/blob/a210809efb34c2dc895fc0c6d96a3412a9097625/cyclonedx/output/__init__.py#L126-L138
We found that some downstream users implemented a behavior-map like that, and when we introduced breaking changes, they often did not upgrade because they would need to change these mappings that were buried somewhere deep in their code.
So we decided to provide and maintain these mappings in the library, so that users don't have to. This led to the API cyclonedx.output.make_outputter()
.
history: v6 API change:
- Removed deprecated function
output.get_instance()
(via [#493])
Use functionoutput.make_outputter()
instead.
Feel free to pullrequest improvements. The doc-sources are here: https://github.com/CycloneDX/cyclonedx-python-lib/tree/main/docs
@jkowalleck Thanks for the great explanation.
I've tried to combine the gist of it in the PR #709. Feel free to give your feedback on it.
This is probably both a bug report and a question.
Since
cyclonedx.output.get_instance()
has been removed via #493 the examples for the outputting in the docs are not valid anymore(bug report):Here comes the question part:
:a: The preferred way (as suggested in the deprecation message) would be using the
cyclonedx.output.make_outputter()
like this ::b: There is also a much simpler way to use the predefined format+schema combined outputs:
Which one of :a: or :b: would be the preferred way?
If we agree on it, I can create a PR to resolve the bug in the docs.