Preferred way for outputting

[hakandilek]

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):

from cyclonedx.output import get_instance, BaseOutput, OutputFormat

outputter: BaseOutput = get_instance(bom=bom, output_format=OutputFormat.JSON)
bom_json: str = outputter.output_as_string()

Here comes the question part:

🅰️ The preferred way (as suggested in the deprecation message) would be using the cyclonedx.output.make_outputter() like this :

from cyclonedx.output import make_outputter, BaseOutput, OutputFormat, SchemaVersion

outputter: BaseOutput = make_outputter(bom=bom, output_format=OutputFormat.JSON, schema_version=SchemaVersion.V1_6)
bom_json: str = outputter.output_as_string()

🅱️ There is also a much simpler way to use the predefined format+schema combined outputs:

from cyclonedx.output.json import JsonV1Dot6

outputter = JsonV1Dot6(bom=bom)
bom_json: str = outputter.output_as_string()

Which one of 🅰️ or 🅱️ would be the preferred way?

If we agree on it, I can create a PR to resolve the bug in the docs.

[jkowalleck]

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:

• cyclonedx-python-lib/examples/complex_serialize.py

  Lines 82 to 83 in a210809

  	my_json_outputter: 'JsonOutputter' = JsonV1Dot5(bom)
  	serialized_json = my_json_outputter.output_as_string(indent=2)

• cyclonedx-python-lib/examples/complex_serialize.py

  Lines 102 to 103 in a210809

  	my_xml_outputter: 'XmlOutputter' = make_outputter(bom, OutputFormat.XML, SchemaVersion.V1_6)
  	serialized_xml = my_xml_outputter.output_as_string(indent=2)

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:

• if you have actual variables for output_format and schema_version, then go with the flexible 🅰️. - here you can inject your variables.
• if 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 🅱️.

cyclonedx-python-lib/cyclonedx/output/__init__.py

Lines 126 to 138 in a210809

	if TYPE_CHECKING: # pragma: no cover
	BY_SCHEMA_VERSION: Mapping[SchemaVersion, Type[BaseOutput]] # noqa:N806
	if OutputFormat.JSON is output_format:
	from .json import BY_SCHEMA_VERSION
	elif OutputFormat.XML is output_format:
	from .xml import BY_SCHEMA_VERSION
	else:
	raise ValueError(f'Unexpected output_format: {output_format!r}')
	klass = BY_SCHEMA_VERSION.get(schema_version, None)
	if klass is None:
	raise ValueError(f'Unknown {output_format.name}/schema_version: {schema_version!r}')
	return klass(bom)

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 [Remove deprecated 6.0.0 #493])
  Use function output.make_outputter() instead.

[hakandilek]

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.