From c2bca323153bbb019366e4b0ae83b59b44e90d00 Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Mon, 10 Apr 2023 18:05:54 -0400 Subject: [PATCH 1/5] format-docs Signed-off-by: Jinzhe Zeng --- dpdata/format.py | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/dpdata/format.py b/dpdata/format.py index c6ba91b7b..7adfd876c 100644 --- a/dpdata/format.py +++ b/dpdata/format.py @@ -7,12 +7,36 @@ class Format(ABC): + """The abstract base class for all formats.""" __FormatPlugin = Plugin() __FromPlugin = Plugin() __ToPlugin = Plugin() @staticmethod def register(key): + """Register a format plugin. + + Returns a decorator for a Format. + + Parameters + ---------- + key : str + The key to register the plugin. + + Returns + ------- + function + The decorator function. + + Examples + -------- + Register a format plugin: + + >>> @Format.register('test') + ... @Format.register('test2') + ... class TestFormat(Format): + ... pass + """ return Format.__FormatPlugin.register(key) @staticmethod @@ -53,10 +77,12 @@ def from_system(self, file_name, **kwargs): ---------- file_name : str file name + **kwargs : dict + other parameters Returns ------- - data: dict + data : dict system data """ raise NotImplementedError( From 8b58eed51fd8e641a97c38017dfa4ffbf56f87a5 Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Wed, 12 Apr 2023 18:01:03 -0400 Subject: [PATCH 2/5] add comments for Format class Signed-off-by: Jinzhe Zeng --- dpdata/format.py | 173 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 164 insertions(+), 9 deletions(-) diff --git a/dpdata/format.py b/dpdata/format.py index 36652eae9..e8a2246cb 100644 --- a/dpdata/format.py +++ b/dpdata/format.py @@ -15,7 +15,14 @@ class Format(ABC): def register(key): """Register a format plugin. - Returns a decorator for a Format. + By default, after a format plugin is registered, the following methods + will be registered as well for System, LabeledSystem, MultiSystems, and + BondOrderSystem: + + - from_{key.replace('/', '_')} + - to_{key.replace('/', '_')} + - from({key}, ...) + - to({key}, ...) Parameters ---------- @@ -40,26 +47,100 @@ def register(key): @staticmethod def register_from(key): + """Register a from method if the target method name is not default. + + Parameters + ---------- + key : str + The key to register the plugin. + + Returns + ------- + function + The decorator function. + + Examples + -------- + Register a from method: + + >>> @Format.register_from('from_test_haha') + ... @Format.register('test) + ... class TestFormat(Format): + ... pass + + This will register a from method named from_test_haha, although the + format name is test. + """ return Format.__FromPlugin.register(key) @staticmethod def register_to(key): + """Register a to method if the target method name is not default. + + Parameters + ---------- + key : str + The key to register the plugin. + + Returns + ------- + function + The decorator function. + + Examples + --------' + Register a to method: + + >>> @Format.register_to('to_test_haha') + ... @Format.register('test') + ... class TestFormat(Format): + ... pass + + This will register a to method named to_test_haha, although the + format name is test. + """ return Format.__ToPlugin.register(key) @staticmethod def get_formats(): + """Get all registered formats.""" return Format.__FormatPlugin.plugins @staticmethod def get_from_methods(): + """Get all registered from methods.""" return Format.__FromPlugin.plugins @staticmethod def get_to_methods(): + """Get all registered to methods.""" return Format.__ToPlugin.plugins @staticmethod def post(func_name): + """Register a post function for from method. + + Such function will be called after the "from" method is called. + + Parameters + ---------- + func_name : str or list of str + The name of the post function. + + Returns + ------- + function + The decorator function. + + Examples + -------- + Register a post function: + + >>> @Format.post('remove_pbc') + ... @Format.register('test') + ... class TestFormat(Format): + ... pass + """ def decorator(object): if not isinstance(func_name, (list, tuple, set)): object.post_func = (func_name,) @@ -70,7 +151,7 @@ def decorator(object): return decorator def from_system(self, file_name, **kwargs): - """System.from. + """Implement System.from that converts from this format to System. Parameters ---------- @@ -82,19 +163,19 @@ def from_system(self, file_name, **kwargs): Returns ------- data : dict - system data + system data, whose keys are defined in System.DTYPES """ raise NotImplementedError( "%s doesn't support System.from" % (self.__class__.__name__) ) def to_system(self, data, *args, **kwargs): - """System.to. + """Implement System.to that converts from System to this format. Parameters ---------- data : dict - system data + system data, whose keys are defined in System.DTYPES *args : list other parameters **kwargs : dict @@ -105,25 +186,84 @@ def to_system(self, data, *args, **kwargs): ) def from_labeled_system(self, file_name, **kwargs): + """Implement LabeledSystem.from that converts from this format to LabeledSystem. + + Parameters + ---------- + file_name : str + file name + **kwargs : dict + other parameters + + Returns + ------- + data : dict + system data, whose keys are defined in LabeledSystem.DTYPES + """ raise NotImplementedError( "%s doesn't support LabeledSystem.from" % (self.__class__.__name__) ) def to_labeled_system(self, data, *args, **kwargs): + """Implement LabeledSystem.to that converts from LabeledSystem to this format. + + By default, LabeledSystem.to will fallback to System.to. + + Parameters + ---------- + data : dict + system data, whose keys are defined in LabeledSystem.DTYPES + *args : list + other parameters + **kwargs : dict + other parameters + """ return self.to_system(data, *args, **kwargs) def from_bond_order_system(self, file_name, **kwargs): + """Implement BondOrderSystem.from that converts from this format to BondOrderSystem. + + Parameters + ---------- + file_name : str + file name + **kwargs : dict + other parameters + + Returns + ------- + data : dict + system data + """ raise NotImplementedError( "%s doesn't support BondOrderSystem.from" % (self.__class__.__name__) ) def to_bond_order_system(self, data, rdkit_mol, *args, **kwargs): + """Implement BondOrderSystem.to that converts from BondOrderSystem to this format. + + By default, BondOrderSystem.to will fallback to LabeledSystem.to. + + Parameters + ---------- + data : dict + system data + rdkit_mol : rdkit.Chem.rdchem.Mol + rdkit mol object + *args : list + other parameters + **kwargs : dict + other parameters + """ return self.to_system(data, *args, **kwargs) class MultiModes: - """File mode for MultiSystems - 0 (default): not implemented - 1: every directory under the top-level directory is a system. + """File mode for MultiSystems. + + The current implemented modes are: + + - 0 (default): not implemented + - 1: every directory under the top-level directory is a system. """ NotImplemented = 0 @@ -132,7 +272,9 @@ class MultiModes: MultiMode = MultiModes.NotImplemented def from_multi_systems(self, directory, **kwargs): - """MultiSystems.from. + """Implement MultiSystems.from that converts from this format to MultiSystems. + + By default, this method follows MultiMode to implement the conversion. Parameters ---------- @@ -157,6 +299,19 @@ def from_multi_systems(self, directory, **kwargs): ) def to_multi_systems(self, formulas, directory, **kwargs): + """Implement MultiSystems.to that converts from MultiSystems to this format. + + By default, this method follows MultiMode to implement the conversion. + + Parameters + ---------- + formulas : list[str] + list of formulas + directory : str + directory of system + **kwargs : dict + other parameters + """ if self.MultiMode == self.MultiModes.Directory: return [os.path.join(directory, ff) for ff in formulas] raise NotImplementedError( From 7c1ad1b1d4becfd7bec8e8cf7306852c58d2f6b1 Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Wed, 12 Apr 2023 18:33:30 -0400 Subject: [PATCH 3/5] improve docs --- dpdata/format.py | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/dpdata/format.py b/dpdata/format.py index e8a2246cb..c7676ecbc 100644 --- a/dpdata/format.py +++ b/dpdata/format.py @@ -6,7 +6,16 @@ class Format(ABC): - """The abstract base class for all formats.""" + """The abstract base class for all formats. + + To add a new format, one should create a new class inherited from this class, and then + + - implement several methods, such as :meth:`from_system`; + - register the format with a key; + - add documentation in the class docstring; + + The new format can be either insider or outside the package. + """ __FormatPlugin = Plugin() __FromPlugin = Plugin() __ToPlugin = Plugin() @@ -16,14 +25,20 @@ def register(key): """Register a format plugin. By default, after a format plugin is registered, the following methods - will be registered as well for System, LabeledSystem, MultiSystems, and - BondOrderSystem: + will be registered as well for :meth:`System`, :meth:`LabeledSystem`, :meth:`MultiSystems`, and + :meth:`BondOrderSystem`: - from_{key.replace('/', '_')} - to_{key.replace('/', '_')} - from({key}, ...) - to({key}, ...) + The decorator should be explicitly executed before :mod:`dpdata.system` + is imported. A module will be imported automatically if it + + - is a submodule of :mod:`dpdata.plugins`; + - is registered at the `dpdata.plugins` entry point + Parameters ---------- key : str From 87f097aa999c9821bf75b749028457382e7fa1f1 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 12 Apr 2023 22:34:03 +0000 Subject: [PATCH 4/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- dpdata/format.py | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/dpdata/format.py b/dpdata/format.py index c7676ecbc..f38b98b57 100644 --- a/dpdata/format.py +++ b/dpdata/format.py @@ -7,15 +7,16 @@ class Format(ABC): """The abstract base class for all formats. - + To add a new format, one should create a new class inherited from this class, and then - + - implement several methods, such as :meth:`from_system`; - register the format with a key; - add documentation in the class docstring; - + The new format can be either insider or outside the package. """ + __FormatPlugin = Plugin() __FromPlugin = Plugin() __ToPlugin = Plugin() @@ -23,7 +24,7 @@ class Format(ABC): @staticmethod def register(key): """Register a format plugin. - + By default, after a format plugin is registered, the following methods will be registered as well for :meth:`System`, :meth:`LabeledSystem`, :meth:`MultiSystems`, and :meth:`BondOrderSystem`: @@ -32,12 +33,12 @@ def register(key): - to_{key.replace('/', '_')} - from({key}, ...) - to({key}, ...) - + The decorator should be explicitly executed before :mod:`dpdata.system` is imported. A module will be imported automatically if it - + - is a submodule of :mod:`dpdata.plugins`; - - is registered at the `dpdata.plugins` entry point + - is registered at the `dpdata.plugins` entry point Parameters ---------- @@ -48,7 +49,7 @@ def register(key): ------- function The decorator function. - + Examples -------- Register a format plugin: @@ -63,7 +64,7 @@ def register(key): @staticmethod def register_from(key): """Register a from method if the target method name is not default. - + Parameters ---------- key : str @@ -73,7 +74,7 @@ def register_from(key): ------- function The decorator function. - + Examples -------- Register a from method: @@ -96,13 +97,14 @@ def register_to(key): ---------- key : str The key to register the plugin. - + Returns ------- function The decorator function. - + Examples + -------- --------' Register a to method: @@ -141,12 +143,12 @@ def post(func_name): ---------- func_name : str or list of str The name of the post function. - + Returns ------- function The decorator function. - + Examples -------- Register a post function: @@ -156,6 +158,7 @@ def post(func_name): ... class TestFormat(Format): ... pass """ + def decorator(object): if not isinstance(func_name, (list, tuple, set)): object.post_func = (func_name,) @@ -221,7 +224,7 @@ def from_labeled_system(self, file_name, **kwargs): def to_labeled_system(self, data, *args, **kwargs): """Implement LabeledSystem.to that converts from LabeledSystem to this format. - + By default, LabeledSystem.to will fallback to System.to. Parameters @@ -244,7 +247,7 @@ def from_bond_order_system(self, file_name, **kwargs): file name **kwargs : dict other parameters - + Returns ------- data : dict From a9c0e4f1cfe9a93c8f107ffa8a8e81711d00276c Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Wed, 12 Apr 2023 18:46:54 -0400 Subject: [PATCH 5/5] improve documentation --- dpdata/format.py | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/dpdata/format.py b/dpdata/format.py index f38b98b57..461d1ad68 100644 --- a/dpdata/format.py +++ b/dpdata/format.py @@ -105,7 +105,6 @@ def register_to(key): Examples -------- - --------' Register a to method: >>> @Format.register_to('to_test_haha') @@ -174,9 +173,9 @@ def from_system(self, file_name, **kwargs): Parameters ---------- file_name : str - file name + file name, i.e. the first argument **kwargs : dict - other parameters + keyword arguments that will be passed from the method Returns ------- @@ -195,9 +194,9 @@ def to_system(self, data, *args, **kwargs): data : dict system data, whose keys are defined in System.DTYPES *args : list - other parameters + arguments that will be passed from the method **kwargs : dict - other parameters + keyword arguments that will be passed from the method """ raise NotImplementedError( "%s doesn't support System.to" % (self.__class__.__name__) @@ -209,9 +208,9 @@ def from_labeled_system(self, file_name, **kwargs): Parameters ---------- file_name : str - file name + file name, i.e. the first argument **kwargs : dict - other parameters + keyword arguments that will be passed from the method Returns ------- @@ -232,9 +231,9 @@ def to_labeled_system(self, data, *args, **kwargs): data : dict system data, whose keys are defined in LabeledSystem.DTYPES *args : list - other parameters + arguments that will be passed from the method **kwargs : dict - other parameters + keyword arguments that will be passed from the method """ return self.to_system(data, *args, **kwargs) @@ -244,9 +243,9 @@ def from_bond_order_system(self, file_name, **kwargs): Parameters ---------- file_name : str - file name + file name, i.e. the first argument **kwargs : dict - other parameters + keyword arguments that will be passed from the method Returns ------- @@ -269,9 +268,9 @@ def to_bond_order_system(self, data, rdkit_mol, *args, **kwargs): rdkit_mol : rdkit.Chem.rdchem.Mol rdkit mol object *args : list - other parameters + arguments that will be passed from the method **kwargs : dict - other parameters + keyword arguments that will be passed from the method """ return self.to_system(data, *args, **kwargs) @@ -299,7 +298,7 @@ def from_multi_systems(self, directory, **kwargs): directory : str directory of system **kwargs : dict - other parameters + keyword arguments that will be passed from the method Returns ------- @@ -328,7 +327,7 @@ def to_multi_systems(self, formulas, directory, **kwargs): directory : str directory of system **kwargs : dict - other parameters + keyword arguments that will be passed from the method """ if self.MultiMode == self.MultiModes.Directory: return [os.path.join(directory, ff) for ff in formulas] @@ -346,7 +345,7 @@ def mix_system(self, *system, type_map, **kwargs): type_map : list of str Maps atom type to name **kwargs : dict - other parameters + keyword arguments that will be passed from the method Returns -------