orgmunge 0.2.0__tar.gz → 0.2.2__tar.gz

orgmunge-0.2.0/README.org → orgmunge-0.2.2/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.1
+Name: orgmunge
+Version: 0.2.2
+Summary: Programmatically modify Orgmode documents
+License: MIT
+Author: durableOne 
+Author-email: era31asj@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: ply (>=3.11,<4.0)
+Description-Content-Type: text/plain
+
 #+title:Orgmunge
 * Motivation and scope
 Orgmunge was born out of the desire to modify Org documents
@@ -120,21 +136,25 @@ compromising your information. See [[https://github.com/durableOne/redactOrg][re
      values. The properties are parsed from the =PROPERTIES= drawer if
      it exists. This attribute can also be set by the user (the value
      supplied must be a dict).
-  2. =headline= returns the heading's headline. This attribute can also
+  2. =inherited_properties=. Same format as the =properties= dict but
+     contains only properties inherited from ancestors.
+  3. =tags= returns a list of all tags (those explicitly defined for
+     this heading and those inherited)
+  4. =headline= returns the heading's headline. This attribute can also
      be set by a user (the value must be a [[*Headline Objects][Headline]] instance).
-  3. =scheduling= is a [[*Scheduling Objects][Scheduling]] object containing information about
+  5. =scheduling= is a [[*Scheduling Objects][Scheduling]] object containing information about
      =SCHEDULED/DEADLINE/CLOSED= timestamps of the heading, if any. Can
      also be set by the user (the value must be a Scheduling instance).
-  4. =drawers= is a list of [[*Drawer Objects][Drawer]] objects containing the drawers
+  6. =drawers= is a list of [[*Drawer Objects][Drawer]] objects containing the drawers
      associated with this heading. When you update the heading's
      =properties= attribute, the =PROPERTIES= drawer is updated the next
      time you access it.
-  5. =children= returns a list of Heading objects that are the direct
+  7. =children= returns a list of Heading objects that are the direct
      children of this heading.
-  6. =parent= returns the parent heading of the current one. If the
+  8. =parent= returns the parent heading of the current one. If the
      current heading is a top-level heading, the root heading will be
      returned.
-  7. =sibling= returns the sibling heading of the current one that comes
+  9. =sibling= returns the sibling heading of the current one that comes
      before it in the tree, if any. The reason this is the sibling
      heading that is formally tracked is because it's the one that
      would adopt the current heading whenever the current heading is
@@ -143,34 +163,37 @@ compromising your information. See [[https://github.com/durableOne/redactOrg][re
      #+begin_src python
        siblings = [c for c in current_heading.parent.children if c is not current_heading]
      #+end_src
-  8. =level= is the heading's level, with 1 being the top level and each
-     sub-level after that being incremented by 1 (the heading's level
-     is the number of "stars" before its headline).
+  10. =level= is the heading's level, with 1 being the top level and each
+      sub-level after that being incremented by 1 (the heading's level
+      is the number of "stars" before its headline).
 - Important methods:
   1. =clocking=. This returns a list of [[*Clocking Objects][Clocking]] objects, parsed
      from the heading's =LOGBOOK= drawer, if any. You can also pass the
      optional boolean parameter =include_children=, which, when True,
      includes clocking information of this heading's children as well.
-  2. =add_child= accepts a Heading object to add as a child to the
+  2. =get_all_properties=. This returns a dict of all properties of the
+     heading, whether directly defined or inherited from the heading's
+     ancestors. The latest-defined value of a property wins over. 
+  3. =add_child= accepts a Heading object to add as a child to the
      current heading. The optional boolean parameter =new= should be set
      to =True= when this is a new heading that was created and needs to
      be assigned a parent. It should be set to =False= (default) when
      the addition of a child is due to a promotion/demotion operation.
-  3. =remove_child= accepts a heading object and deletes it from the
+  4. =remove_child= accepts a heading object and deletes it from the
      current heading's children if it's a child of the current
      heading.
-  4. =promote= promotes the current heading one level. If the heading has
+  5. =promote= promotes the current heading one level. If the heading has
      children, they would be orphaned so this raises a
      =ValueError=. Technically, Org allows you to have, say, level 3
      headings under a level 1 heading, but =orgmunge= does not allow
      this to make parsing the tree easier.
-  5. =promote_tree= promotes the current heading and all its
+  6. =promote_tree= promotes the current heading and all its
      descendants. Use this if the heading you want to promote has
      children.
-  6. =demote= demotes the current heading one level. If the current
+  7. =demote= demotes the current heading one level. If the current
      heading has no sibling to adopt it, the demotion attempt fails
      and raises a =ValueError=.
-  7. =demote_tree= is the equivalent of =promote_tree= for demotion.
+  8. =demote_tree= is the equivalent of =promote_tree= for demotion.
 *** Headline Objects
 - Important attributes:
   1. =done= is a boolean attribute that determines whether the headline
@@ -295,6 +318,16 @@ ignored if =exact= is =True=.
 Uses =filter_headings= under the hood so will return a generator of
 matching headings.
 
+*** Search for Headings by Path
+Use =Org.get_heading_by_path= to search for a heading with the given path:
+#+begin_src python
+  Org.get_heading_by_path(path, exact=False, re_flags=0)
+#+end_src
+=path= is a list of heading titles. Each member is interpreted the same
+way the =search_string= argument of =get_headings_by_title= is
+interpreted. This function returns the first heading of the tree that
+matches the given path or =None= if no such heading is found.
+
 * License
 #+INCLUDE: ./LICENSE
 
@@ -312,3 +345,4 @@ Thanks to these wonderful people for contributing time and code:
 - [[https://github.com/Nalisarc][Nalisarc]]
 - [[https://github.com/ispringle][ispringle]]
 - [[https://github.com/crdoconnor][crdoconnor]]
+

orgmunge-0.2.0/PKG-INFO → orgmunge-0.2.2/README.org

@@ -1,18 +1,3 @@
-Metadata-Version: 2.1
-Name: orgmunge
-Version: 0.2.0
-Summary: Programmatically modify Orgmode documents
-License: MIT
-Author: durableOne 
-Author-email: era31asj@gmail.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Requires-Dist: ply (>=3.11,<4.0)
-Description-Content-Type: text/plain
-
 #+title:Orgmunge
 * Motivation and scope
 Orgmunge was born out of the desire to modify Org documents
@@ -135,21 +120,25 @@ compromising your information. See [[https://github.com/durableOne/redactOrg][re
      values. The properties are parsed from the =PROPERTIES= drawer if
      it exists. This attribute can also be set by the user (the value
      supplied must be a dict).
-  2. =headline= returns the heading's headline. This attribute can also
+  2. =inherited_properties=. Same format as the =properties= dict but
+     contains only properties inherited from ancestors.
+  3. =tags= returns a list of all tags (those explicitly defined for
+     this heading and those inherited)
+  4. =headline= returns the heading's headline. This attribute can also
      be set by a user (the value must be a [[*Headline Objects][Headline]] instance).
-  3. =scheduling= is a [[*Scheduling Objects][Scheduling]] object containing information about
+  5. =scheduling= is a [[*Scheduling Objects][Scheduling]] object containing information about
      =SCHEDULED/DEADLINE/CLOSED= timestamps of the heading, if any. Can
      also be set by the user (the value must be a Scheduling instance).
-  4. =drawers= is a list of [[*Drawer Objects][Drawer]] objects containing the drawers
+  6. =drawers= is a list of [[*Drawer Objects][Drawer]] objects containing the drawers
      associated with this heading. When you update the heading's
      =properties= attribute, the =PROPERTIES= drawer is updated the next
      time you access it.
-  5. =children= returns a list of Heading objects that are the direct
+  7. =children= returns a list of Heading objects that are the direct
      children of this heading.
-  6. =parent= returns the parent heading of the current one. If the
+  8. =parent= returns the parent heading of the current one. If the
      current heading is a top-level heading, the root heading will be
      returned.
-  7. =sibling= returns the sibling heading of the current one that comes
+  9. =sibling= returns the sibling heading of the current one that comes
      before it in the tree, if any. The reason this is the sibling
      heading that is formally tracked is because it's the one that
      would adopt the current heading whenever the current heading is
@@ -158,34 +147,37 @@ compromising your information. See [[https://github.com/durableOne/redactOrg][re
      #+begin_src python
        siblings = [c for c in current_heading.parent.children if c is not current_heading]
      #+end_src
-  8. =level= is the heading's level, with 1 being the top level and each
-     sub-level after that being incremented by 1 (the heading's level
-     is the number of "stars" before its headline).
+  10. =level= is the heading's level, with 1 being the top level and each
+      sub-level after that being incremented by 1 (the heading's level
+      is the number of "stars" before its headline).
 - Important methods:
   1. =clocking=. This returns a list of [[*Clocking Objects][Clocking]] objects, parsed
      from the heading's =LOGBOOK= drawer, if any. You can also pass the
      optional boolean parameter =include_children=, which, when True,
      includes clocking information of this heading's children as well.
-  2. =add_child= accepts a Heading object to add as a child to the
+  2. =get_all_properties=. This returns a dict of all properties of the
+     heading, whether directly defined or inherited from the heading's
+     ancestors. The latest-defined value of a property wins over. 
+  3. =add_child= accepts a Heading object to add as a child to the
      current heading. The optional boolean parameter =new= should be set
      to =True= when this is a new heading that was created and needs to
      be assigned a parent. It should be set to =False= (default) when
      the addition of a child is due to a promotion/demotion operation.
-  3. =remove_child= accepts a heading object and deletes it from the
+  4. =remove_child= accepts a heading object and deletes it from the
      current heading's children if it's a child of the current
      heading.
-  4. =promote= promotes the current heading one level. If the heading has
+  5. =promote= promotes the current heading one level. If the heading has
      children, they would be orphaned so this raises a
      =ValueError=. Technically, Org allows you to have, say, level 3
      headings under a level 1 heading, but =orgmunge= does not allow
      this to make parsing the tree easier.
-  5. =promote_tree= promotes the current heading and all its
+  6. =promote_tree= promotes the current heading and all its
      descendants. Use this if the heading you want to promote has
      children.
-  6. =demote= demotes the current heading one level. If the current
+  7. =demote= demotes the current heading one level. If the current
      heading has no sibling to adopt it, the demotion attempt fails
      and raises a =ValueError=.
-  7. =demote_tree= is the equivalent of =promote_tree= for demotion.
+  8. =demote_tree= is the equivalent of =promote_tree= for demotion.
 *** Headline Objects
 - Important attributes:
   1. =done= is a boolean attribute that determines whether the headline
@@ -310,6 +302,16 @@ ignored if =exact= is =True=.
 Uses =filter_headings= under the hood so will return a generator of
 matching headings.
 
+*** Search for Headings by Path
+Use =Org.get_heading_by_path= to search for a heading with the given path:
+#+begin_src python
+  Org.get_heading_by_path(path, exact=False, re_flags=0)
+#+end_src
+=path= is a list of heading titles. Each member is interpreted the same
+way the =search_string= argument of =get_headings_by_title= is
+interpreted. This function returns the first heading of the tree that
+matches the given path or =None= if no such heading is found.
+
 * License
 #+INCLUDE: ./LICENSE
 
@@ -327,4 +329,3 @@ Thanks to these wonderful people for contributing time and code:
 - [[https://github.com/Nalisarc][Nalisarc]]
 - [[https://github.com/ispringle][ispringle]]
 - [[https://github.com/crdoconnor][crdoconnor]]
-

{orgmunge-0.2.0 → orgmunge-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "orgmunge"
-version = "0.2.0"
+version = "0.2.2"
 description = "Programmatically modify Orgmode documents"
 authors = ["durableOne  <era31asj@gmail.com>"]
 license = "MIT"

{orgmunge-0.2.0 → orgmunge-0.2.2}/src/orgmunge/__init__.py

@@ -7,7 +7,7 @@ import platform
 from .parser import Parser
 from .lexer import Lexer
 from .classes import *
-from typing import List, Dict, Optional, Generator, Callable
+from typing import List, Dict, Optional, Generator, Callable, Iterable
 
 class Org:
     def _parse_todos(self, inp: str) -> Optional[Dict[str, Dict[str, str]]]:
@@ -164,6 +164,25 @@ class Org:
             condition = lambda h: bool(re.search(fr'{search_string}', h.title, flags=re_flags))
         return self.filter_headings(condition)
 
+    def get_heading_by_path(self, path: List[str], exact: bool = False, re_flags: int = 0) -> Optional[Heading]:
+        """Return a heading by its given path. If exact is True, interpret the given path
+        as strings to match node titles exactly; otherwise, interpret them as regexes. If
+        no heading matches the given path, return None"""
+        if exact:
+            condition = lambda heading: heading.title == path[-1]
+        else:
+            condition = lambda heading: bool(re.search(fr'{path[-1]}', heading.title, flags=re_flags))
+        if not path:
+            return self.root
+        else:
+            headings_at_this_level = self.filter_headings(lambda h: h.level == len(path) and condition(h))  
+            candidates = (h for h in headings_at_this_level
+                          if h.parent is self.get_heading_by_path(path[:-1], exact=exact, re_flags=re_flags))
+            try:
+                return next(candidates)
+            except StopIteration:
+                return None
+        
     def __repr__(self):
         result = ''
         for keyword in self.metadata:

{orgmunge-0.2.0 → orgmunge-0.2.2}/src/orgmunge/classes.py

@@ -135,7 +135,6 @@ class Priority:
             return False
         else:
             return str(self) == str(other)
-
 class Headline:
     def __init__(self, todos, level: str, comment: bool = False,
                todo: Optional[str] = None, priority: Optional[str] = None,
@@ -159,10 +158,10 @@ class Headline:
         raise AttributeError("Can't set the 'done' attribute")
 
     def _is_done(self):
-        if self.todo in self._done_states:
-            return True
-        elif self.todo is None or self.todo in self._todo_states:
+        if self.todo is None or self.todo in self._todo_states:
             return False
+        elif self.todo in self._done_states:
+            return True
         else:
             raise ValueError(f"Uncategorized todo state {self.todo}")
 
@@ -252,7 +251,6 @@ class Headline:
             return False
         else:
             return str(self) == str(other)
-
 class TimeStamp:
     def __init__(self, timestamp_str: str):
         is_active = re.search(Lexer.ATIMESTAMP, timestamp_str)
@@ -376,7 +374,6 @@ class TimeStamp:
             return False
         else:
             return str(self) == str(other)
-
 class Scheduling:
     _closed = None
     _scheduled = None
@@ -442,7 +439,6 @@ class Scheduling:
             return False
         else:
             return str(self) == str(other)
-
 class Drawer:
     def __init__(self, drawer_string: str):
         self.name = re.sub(r':', '', drawer_string.split('\n')[0])
@@ -458,7 +454,6 @@ class Drawer:
             return False
         else:
             return str(self) == str(other)
-        
 class Clocking:
     def __init__(self, start_time: str, end_time: Optional[str] = None):
         self._start_time = dt.strptime(start_time, ORG_TIME_FORMAT)
@@ -526,7 +521,6 @@ class Clocking:
             return False
         else:
             return str(self) == str(other)
-
 class Heading():
     def __init__(self, headline: Headline, contents: Tuple[Scheduling, List[Drawer], str]):
         self._headline = headline
@@ -534,6 +528,7 @@ class Heading():
         self._children = []
         self._parent = None
         self._sibling = None
+        self._inherited_properties = dict()
         if self.body:
             self.timestamps = [TimeStamp(t[0]) for t in re.findall(fr'({Lexer.ATIMESTAMP}|{Lexer.ITIMESTAMP})', self.body)]
         if self._drawers:
@@ -567,9 +562,9 @@ class Heading():
     def _get_clocking_info(self) -> List[Clocking]:
         if not self.drawers:
             return []
-        logbook = [d for d in self.drawers if d.name == 'LOGBOOK']
+        logbook = self.get_drawer_by_name('LOGBOOK')
         if logbook:
-            return [self._parse_clock_line(l) for l in logbook[0].contents if re.search(r'^\s*CLOCK:', l)]
+            return [self._parse_clock_line(l) for l in logbook.contents if re.search(r'^\s*CLOCK:', l)]
         else:
             return []
 
@@ -580,6 +575,27 @@ class Heading():
     def _get_properties_string(self) -> str:
         return "\n".join([f":{k}:{' '*7}{v}" for k, v in self.properties.items()])
 
+    @property
+    def inherited_properties(self):
+        if not self._inherited_properties:
+            if self.parent:
+                self._inherited_properties = {**self.parent.inherited_properties, **self.parent.properties}
+        return self._inherited_properties
+
+    @inherited_properties.setter
+    def inherited_properties(self, _):
+        raise AttributeError("Can't set the inherited properties of a heading")
+    
+    @property
+    def tags(self):
+        self_tags = self.headline.tags or []
+        parent_tags = (self.parent.tags if self.parent else None) or []
+        return list(set(self_tags + parent_tags))
+
+    @tags.setter
+    def tags(self, _):
+        raise AttributeError("Can't set the tags of a heading, use headline instead.")
+    
     @property
     def properties(self):
         return self._properties
@@ -593,6 +609,8 @@ class Heading():
             for key in val:
                 self._properties[key] = val[key]
 
+    def get_all_properties(self) -> Dict[str, str]:
+        return {**self.inherited_properties, **self.properties}
 
     def clocking(self, include_children: bool = False) -> List[Clocking]:
         "Return the clocking information of the given headline and possibly its children."
@@ -602,6 +620,13 @@ class Heading():
         else:
             return own_clocking
 
+    def get_drawer_by_name(self, name: str) -> Optional[Drawer]:
+        "Return the named drawer if it exists, or None if it doesn't"
+        try:
+            return next(d for d in self.drawers if d.name == name)
+        except StopIteration:
+            return None
+
     @property
     def headline(self):
         return self._headline

{orgmunge-0.2.0 → orgmunge-0.2.2}/src/orgmunge/lexer.py

@@ -34,7 +34,7 @@ class Lexer:
 
         def t_error(t):
             print(f"Illegal character encountered: {t.value[0]}")
-            t.lexer.skip(1)
+            raise ValueError("Lexer error!")
 
         self.todos = todos
         all_todo_keywords = {**todos['todo_states'], **todos['done_states']}
@@ -94,7 +94,7 @@ class Lexer:
             return t
 
         def t_SPACE(t):
-            r'[ \t]+'
+            r'[^\S\r\n]+'
             return t
 
         def t_TEXT(t):