DOC: finalize documentation (#15)

* DOC: update docstrings

* FIX: pd.Series is not generic

* DOC: update README.rst

* DOC: remove RST reference to pandas from README.rst

* DOC: remove type hints from README.rst

* DOC: add tutorial for object-oriented API

* DOC: remove obsolete EXCLUDE_MODULES option

* DOC: update hyperlinks in README.rst

* DOC: fix docstrings

* DOC: hide source link in conf_base.py

* CODE: ignore erroneous mypy error for non-generic pd.Series

* FIX: link to home.html

* DOC: update the FAQ

* DOC: update the README.rst intro section

* DOC: add copyright notice

* DOC: update BCG URL

* DOC: update API landing page

* DOC: update version to 1.0.0

README.rst

@@ -7,8 +7,11 @@ Introduction to *fluxus*
 
 *fluxus* is a Python framework designed by `BCG X <https://www.bcg.com/x>`_ to
 streamline the development of complex data processing pipelines (called *flows*),
-enabling users to quickly and efficiently build, test, and deploy data workflows,
-making complex operations more manageable.
+enabling users to quickly and efficiently build, test, and deploy highly concurrent
+workflows, making complex operations more manageable.
+
+**FLUXUS** is inspired by the data stream paradigm and is designed to be simple,
+expressive, and composable.
 
 **FLUXUS** is inspired by the data stream paradigm and is designed to be simple,
 expressive, and composable.

sphinx/add_copyright_notice.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+import os
+
+# Define the copyright notice
+COPYRIGHT_NOTICE = """\
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+"""
+
+
+def add_copyright_notice(file_path):
+    with open(file_path) as file:
+        content = file.read()
+
+    if (
+        COPYRIGHT_NOTICE.strip() not in content
+    ):  # Avoid adding the notice if it's already present
+        with open(file_path, "w") as file:
+            file.write(COPYRIGHT_NOTICE + "\n" + content)
+
+
+def recursively_add_notice_to_py_files(directory):
+    for root, _, files in os.walk(directory):
+        for file in files:
+            if file.endswith(".py"):
+                file_path = os.path.join(root, file)
+                add_copyright_notice(file_path)
+
+
+# Specify the directory you want to start the search from
+start_directory = "../src"  # Replace with your directory path
+
+recursively_add_notice_to_py_files(start_directory)
+
+print("Copyright notice added to all .py files.")

sphinx/source/faq.rst

@@ -10,13 +10,65 @@ FAQ
 About the project
 -----------------
 
-What is FLUXUS for?
-~~~~~~~~~~~~~~~~~~~
+What is *fluxus* for?
+~~~~~~~~~~~~~~~~~~~~~
 
-…
+*fluxus* is a Python framework designed by `BCG X <https://www.bcg.com/x>`_ to
+streamline the development of complex data processing pipelines (called *flows*),
+enabling users to quickly and efficiently build, test, and deploy highly concurrent
+workflows, making complex operations more manageable.
 
-Who developed FLUXUS, and why?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**FLUXUS** is inspired by the data stream paradigm and is designed to be simple,
+expressive, and composable.
 
-…
+Who developed *fluxus*, and why?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+*fluxus* was developed by the Responsible AI team at
+`BCG X <https://www.bcg.com/x>`_, primarily to provide a scalable
+and efficient way to rapidly stand up highly concurrent red teaming workloads for
+GenAI testing and evaluation.
+
+Given that other use cases for *fluxus* are likely to emerge, we decided to publish
+the flow management portion of the codebase as a a separate open-source project.
+
+What is the origin of the name *fluxus*?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The name *fluxus* is derived from the Latin word for "flow" or "stream." The name
+was chosen to reflect the project's focus on data streams and the flow of data
+through a pipeline.
+
+How does *fluxus* differ from other pipelining/workflow libraries?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*fluxus* is designed to be simple, expressive, and composable. It is built on top
+of the `asyncio <https://docs.python.org/3/library/asyncio.html>`_ library, which
+provides a powerful and flexible way to write concurrent code in Python.
+
+*fluxus* is also designed to be highly extensible, allowing users to easily add
+new components and customize existing ones. It provides both a functional API for
+quickly and intuitively building flows using dictionaries as their primary data
+structures, as well as a class-based API for more complex flows that require
+custom data types.
+
+Finally, *fluxus* is designed to be lightweight and efficient, managing the complexities
+of concurrency and parallelism behind the scenes so that users can focus on building
+their pipelines without worrying about the underlying implementation details.
+
+What are examples of use cases for *fluxus*?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*fluxus* is designed to be a general-purpose framework for building data processing
+pipelines, so it can be used in a wide variety of applications.  It is particularly
+powerful for building highly concurrent workflows that make heavy use of I/O-bound
+operations, such as network requests, file I/O, and database queries.
+
+Some examples of use cases for *fluxus* include:
+
+- Real-time data processing
+- ETL (Extract, Transform, Load) pipelines
+- Machine learning workflows
+- Data extraction
+- Data aggregation and analysis
+- Red teaming and security testing

src/fluxus/__init__.py

@@ -1,5 +1,21 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
-This module is designed to handle data flows in a pipeline-like manner. It provides a
+*fluxus* is designed to handle data flows in a pipeline-like manner. It provides a
 set of classes that represent different components of a data flow, such as producers,
 transformers, and consumers. These components can be combined to form complex data
 processing pipelines.
@@ -25,19 +41,17 @@
     This class represents a sequence of producers, transformers, and
     consumers that can be executed to produce a result.
 
-The module also provides classes for concurrent groups of producers
-(:class:`.ConcurrentProducer`) and transformers (:class:`.ConcurrentTransformer`), and
-for handling asynchronous operations (:class:`.AsyncProducer`,
-:class:`.AsyncTransformer`, :class:`.AsyncConsumer`).
+The module also provides classes for handling asynchronous operations
+(:class:`.AsyncProducer`, :class:`.AsyncTransformer`, :class:`.AsyncConsumer`).
 
 The ``>>`` operator is overloaded in these classes to allow for easy chaining of
 operations. For example, a producer can be connected to a transformer, which can then
 be connected to a consumer, forming a complete data flow.
 
 Groups of concurrent producers or transformers can be created using the ``&`` operator.
 
-The :mod:`.core.flow` package is designed to be flexible and extensible, allowing for
-complex data processing pipelines to be built with relative ease.
+*fluxus* package is designed to be flexible and extensible, allowing for complex
+data flows to be built with ease.
 """
 
 from ._consumer import *
@@ -47,4 +61,4 @@
 from ._transformer import *
 from ._warning import *
 
-__version__ = "1.0rc4"
+__version__ = "1.0.0"

src/fluxus/_consumer.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Implementation of conduit base classes.
 """

src/fluxus/_flow.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Implementation of conduit base classes.
 """

src/fluxus/_passthrough.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Implementation of conduit and subconduit base classes
 """

src/fluxus/_producer.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Implementation of producers.
 """

src/fluxus/_transformer.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Implementation of transformers.
 """

src/fluxus/_warning.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 A warning class specific to the `flow` package.
 """

src/fluxus/core/__init__.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Core classes used internally by *fluxus*.
 

src/fluxus/core/_base.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Implementation of `source` and `processor` base classes.
 

src/fluxus/core/_chained_base_.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Implementation of composition classes.
 """

src/fluxus/core/_concurrent.py

@@ -1,3 +1,19 @@
+# -----------------------------------------------------------------------------
+# © 2024 Boston Consulting Group. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
 """
 Implementation of ``ConcurrentConduit``.
 """