arc-utils 1.2.1__tar.gz → 1.3__tar.gz

arc_utils-1.3/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: arc-utils
+Version: 1.3
+Summary: Python utilities for use with Esri ArcGIS Pro software
+Author-email: Grant Herbert <gdherbert@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/gdherbert/arc_utils
+Project-URL: Download, https://github.com/gdherbert/arc_utils/tree/1.3
+Keywords: esri,arcpy,arcgis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Dynamic: license-file
+
+# README #
+
+
+### What is this repository for? ###
+* A collection of (mostly) arcpy related utilities for use within ArcGIS Pro (Python 3).
+Shortcuts for accessing elements of a map document, performing various data discovery tasks on a table or geodatabase
+
+### How do I get set up? ###
+
+Install from PyPI:
+
+```bash
+pip install arc-utils
+```
+
+For local development and editable usage from clone:
+
+```bash
+python -m pip install -e .
+```
+
+To use the utilities:
+
+* in the python window in ArcGIS Pro
+
+``import arc_utils as au``
+
+* typing ``au.`` will now reveal the modules and functions available to you if you have autocomplete on
+
+* Depends on arcpy (only available with Esri license)
+
+### Example usage ###
+
+``import arc_utils as au``
+
+``tbl = au.table.TableObj(path to featureclass)``
+
+# list all fields 
+
+``print(tbl.fields)``
+
+``pro_doc = au.aprx.AprxObj(“CURRENT”)``
+
+``pro_doc.maps`` >> [<arcpy._mp.Map object at 0x000001A4AECBF108>, <arcpy._mp.Map object at 0x000001A4AEBB6608>]
+
+``pro_doc.maps[0].name`` >> ‘Map’
+
+### Accepted Input Types ###
+
+Most path parameters now accept:
+
+* string path
+* ``pathlib.Path`` / other path-like objects
+* wrapper objects with ``.path``
+* ArcGIS layer/table objects with ``.catalogPath`` or ``.dataSource`` (where applicable)
+
+Invalid paths raise ``ValueError("invalid path")``.
+
+Constructor acceptance is preserved (for example, passing path-like and wrapper objects directly to ``TableObj``, ``GDBObj``, and ``AprxObj``).
+
+### Exporting field values to Excel ###
+
+```python
+import arc_utils as au
+from openpyxl import Workbook
+
+# Single table export with class method
+tbl = au.table.TableObj(r"C:\path\to\featureclass")
+wb = Workbook()
+ws = wb.active
+tbl.export_fields_to_worksheet(ws)
+wb.save(r"C:\path\to\schema_values.xlsx")
+```
+
+```python
+# Multi-layer export with module function
+layers = [r"C:\path\to\layer1", r"C:\path\to\layer2"]
+au.table.export_field_sets(layers, r"C:\path\to\all_layers.xlsx")
+```
+
+```python
+# Worksheet naming behavior:
+# use_lyr_alias=True -> prefer alias/name (human-readable)
+# use_lyr_alias=False -> use full table path (traceable)
+au.table.export_field_sets(layers, r"C:\path\to\all_layers.xlsx", use_lyr_alias=True)
+au.table.export_field_sets(layers, r"C:\path\to\all_layers_by_path.xlsx", use_lyr_alias=False)
+```
+
+```python
+# Duplicate detection outputs
+tbl = au.table.TableObj(r"C:\path\to\featureclass")
+dup_values = tbl.find_duplicate_field_values("STATUS", output="set")
+dup_rows_df = tbl.find_duplicate_field_values(["STATUS", "TYPE"], output="df")
+```
+
+### Contribution guidelines ###
+
+Contributions welcomed, this is a starting point for various utilities that I think could be useful within ArcGIS Pro.

arc_utils-1.3/README.md

@@ -0,0 +1,98 @@
+# README #
+
+
+### What is this repository for? ###
+* A collection of (mostly) arcpy related utilities for use within ArcGIS Pro (Python 3).
+Shortcuts for accessing elements of a map document, performing various data discovery tasks on a table or geodatabase
+
+### How do I get set up? ###
+
+Install from PyPI:
+
+```bash
+pip install arc-utils
+```
+
+For local development and editable usage from clone:
+
+```bash
+python -m pip install -e .
+```
+
+To use the utilities:
+
+* in the python window in ArcGIS Pro
+
+``import arc_utils as au``
+
+* typing ``au.`` will now reveal the modules and functions available to you if you have autocomplete on
+
+* Depends on arcpy (only available with Esri license)
+
+### Example usage ###
+
+``import arc_utils as au``
+
+``tbl = au.table.TableObj(path to featureclass)``
+
+# list all fields 
+
+``print(tbl.fields)``
+
+``pro_doc = au.aprx.AprxObj(“CURRENT”)``
+
+``pro_doc.maps`` >> [<arcpy._mp.Map object at 0x000001A4AECBF108>, <arcpy._mp.Map object at 0x000001A4AEBB6608>]
+
+``pro_doc.maps[0].name`` >> ‘Map’
+
+### Accepted Input Types ###
+
+Most path parameters now accept:
+
+* string path
+* ``pathlib.Path`` / other path-like objects
+* wrapper objects with ``.path``
+* ArcGIS layer/table objects with ``.catalogPath`` or ``.dataSource`` (where applicable)
+
+Invalid paths raise ``ValueError("invalid path")``.
+
+Constructor acceptance is preserved (for example, passing path-like and wrapper objects directly to ``TableObj``, ``GDBObj``, and ``AprxObj``).
+
+### Exporting field values to Excel ###
+
+```python
+import arc_utils as au
+from openpyxl import Workbook
+
+# Single table export with class method
+tbl = au.table.TableObj(r"C:\path\to\featureclass")
+wb = Workbook()
+ws = wb.active
+tbl.export_fields_to_worksheet(ws)
+wb.save(r"C:\path\to\schema_values.xlsx")
+```
+
+```python
+# Multi-layer export with module function
+layers = [r"C:\path\to\layer1", r"C:\path\to\layer2"]
+au.table.export_field_sets(layers, r"C:\path\to\all_layers.xlsx")
+```
+
+```python
+# Worksheet naming behavior:
+# use_lyr_alias=True -> prefer alias/name (human-readable)
+# use_lyr_alias=False -> use full table path (traceable)
+au.table.export_field_sets(layers, r"C:\path\to\all_layers.xlsx", use_lyr_alias=True)
+au.table.export_field_sets(layers, r"C:\path\to\all_layers_by_path.xlsx", use_lyr_alias=False)
+```
+
+```python
+# Duplicate detection outputs
+tbl = au.table.TableObj(r"C:\path\to\featureclass")
+dup_values = tbl.find_duplicate_field_values("STATUS", output="set")
+dup_rows_df = tbl.find_duplicate_field_values(["STATUS", "TYPE"], output="df")
+```
+
+### Contribution guidelines ###
+
+Contributions welcomed, this is a starting point for various utilities that I think could be useful within ArcGIS Pro.

arc_utils-1.3/arc_utils/_inputs.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+"""Shared input coercion helpers for arc_utils."""
+import os
+import arcpy
+
+
+def _normalize_to_sequence(values):
+    """Return a list from single or multi-value inputs.
+
+    Strings and path-like values are treated as a single item.
+    """
+    if isinstance(values, (list, tuple, set)):
+        return list(values)
+    return [values]
+
+
+def _to_path_str(value):
+    """Convert path-like values to str where possible."""
+    if value is None:
+        return None
+    try:
+        value = os.fspath(value)
+    except TypeError:
+        return None
+    if isinstance(value, bytes):
+        value = value.decode()
+    return value
+
+
+def _resolve_dataset_path(value, arg_name="value"):
+    """Resolve supported dataset inputs to a path string.
+
+    Supported inputs:
+    - str and pathlib.Path / os.PathLike
+    - ArcGIS Pro layer-name strings (resolved via arcpy.Describe(...).catalogPath)
+    - objects exposing .path (wrapper objects)
+    - ArcGIS Pro map/layer objects exposing .catalogPath or .dataSource
+    """
+    def _resolve_candidate(candidate):
+        """Resolve map layer names and object references to catalog paths."""
+        try:
+            desc = arcpy.Describe(candidate)
+            if hasattr(desc, "catalogPath") and desc.catalogPath:
+                return os.path.abspath(desc.catalogPath)
+        except Exception:
+            pass
+        return os.path.abspath(candidate)
+
+    for attr in ("path", "catalogPath", "dataSource"):
+        if hasattr(value, attr):
+            candidate = _to_path_str(getattr(value, attr))
+            if candidate:
+                return _resolve_candidate(candidate)
+
+    direct = _to_path_str(value)
+    if direct:
+        return _resolve_candidate(direct)
+
+    raise TypeError("{} must be a path-like string or object with a valid path".format(arg_name))
+
+
+def _resolve_aprx_path(value, arg_name="value"):
+    """Resolve Aprx path input, preserving CURRENT special value."""
+    direct = _to_path_str(value)
+    if isinstance(direct, str) and direct.upper() == "CURRENT":
+        return "CURRENT"
+
+    for attr in ("path", "catalogPath", "dataSource"):
+        if hasattr(value, attr):
+            candidate = _to_path_str(getattr(value, attr))
+            if isinstance(candidate, str) and candidate.upper() == "CURRENT":
+                return "CURRENT"
+            if candidate:
+                return os.path.abspath(candidate)
+
+    if direct:
+        return os.path.abspath(direct)
+
+    raise TypeError("{} must be a path-like string or object with a valid path".format(arg_name))
+
+
+def _ensure_valid_path(path):
+    """Validate ArcGIS path-like input and raise a consistent error."""
+    if not arcpy.Exists(path):
+        raise ValueError("invalid path")
+    return path
+
+
+def _input_display_name(value, default_name=None):
+    """Best-effort human-readable name for logs and worksheet names."""
+    for attr in ("name",):
+        if hasattr(value, attr):
+            candidate = getattr(value, attr)
+            if candidate:
+                return str(candidate)
+
+    for attr in ("path", "catalogPath", "dataSource"):
+        if hasattr(value, attr):
+            candidate = getattr(value, attr)
+            if candidate:
+                return str(candidate)
+
+    if default_name is not None:
+        return str(default_name)
+    return str(value)

{arc_utils-1.2.1 → arc_utils-1.3}/arc_utils/aprx.py

@@ -3,20 +3,28 @@
 """
 
 import arcpy
+import os
+from ._inputs import _resolve_aprx_path
 
 class AprxObj(object):
     """ provide methods for working with a ArcGIS Pro aprx file
     all standard arcpy methods are available via .aprx
     Usage: pro_doc = arc_utils.aprx.AprxObj(path)
     :param
-        path: a string representing an aprx file, 
-        or "CURRENT" if used in ArcGIS Pro Python window
+        path: aprx input accepted as
+            - string path
+            - pathlib.Path / os.PathLike
+            - wrapper object exposing .path
+            - "CURRENT" if used in ArcGIS Pro Python window
+        invalid paths raise ValueError("invalid path")
     """
     def __init__(self, aprx_path):
         """ :param path to aprx or "CURRENT"
         """
-        self.aprx = arcpy.mp.ArcGISProject(aprx_path)
-        self.path = aprx_path
+        self.path = _resolve_aprx_path(aprx_path, arg_name="aprx_path")
+        if self.path != "CURRENT" and not os.path.exists(self.path):
+            raise ValueError("invalid path")
+        self.aprx = arcpy.mp.ArcGISProject(self.path)
         self.maps = self.get_maps()
         self.layouts = self.get_layouts()
         

{arc_utils-1.2.1 → arc_utils-1.3}/arc_utils/gdb.py

@@ -1,23 +1,29 @@
 # -*- coding: utf-8 -*-
 """utilities for working with geodatabases and reporting on geodatabase contents
 """
-from __future__ import print_function, unicode_literals, absolute_import
 import os
 import arcpy
 from .output import get_valid_output_path
 from .output import output_msg
+from ._inputs import _ensure_valid_path
+from ._inputs import _normalize_to_sequence
+from ._inputs import _resolve_dataset_path
 
 class GDBObj(object):
     """ provide properties for working with a GDB
     Usage: gdb = arc_utils.gdb.GDBObj(path)
     :param
-        path: a string representing a GDB connection/path
+        path: geodatabase input accepted as
+            - string path
+            - pathlib.Path / os.PathLike
+            - wrapper object exposing .path
+            - ArcGIS object exposing .catalogPath or .dataSource
     """
     def __init__(self, gdb_path):
         """ sets up reference to table
         adds properties and methods
         """
-        self.path = gdb_path
+        self.path = _ensure_valid_path(_resolve_dataset_path(gdb_path, arg_name="gdb_path"))
         self.describe_obj = self._describe_object()
         self.feature_classes = self.get_feature_class_names()
         self.tables = self.get_table_names()
@@ -77,8 +83,8 @@ def report_all_fc_as_text(geodatabase, output_file=None, sep='\t'):
     """Create a text report of all fields in all featureclasses/tables from a geodatabase
     to specified output file.
 
-    :param geodatabase {String}
-        Path or reference to a geodatabase.
+    :param geodatabase {String|pathlike|object}
+        Geodatabase path or object reference.
     
     :param output_file {String}
         Path or reference to a text file. If not supplied defaults to gdb directory.
@@ -88,10 +94,13 @@ def report_all_fc_as_text(geodatabase, output_file=None, sep='\t'):
     """
     default_env = arcpy.env.workspace
     try:
+        geodatabase = _ensure_valid_path(_resolve_dataset_path(geodatabase, arg_name="geodatabase"))
         desc = arcpy.Describe(geodatabase)
         arcpy.env.workspace = geodatabase
         if not output_file:
             path = get_valid_output_path(desc.Path)
+            if not path:
+                raise ValueError("invalid output path")
             output_file = os.path.join(path, desc.name.split(".")[0] + ".txt")
 
         output_msg("Writing to: {0}".format(output_file))
@@ -124,7 +133,7 @@ def report_all_fc_as_text(geodatabase, output_file=None, sep='\t'):
 
             for dataset in datasets:
                 for fc in arcpy.ListFeatureClasses(feature_dataset=dataset):
-                    output_msg("Processing Dataset: {0} \ FeatureClass: {1}".format(dataset, fc))
+                    output_msg("Processing Dataset: {0} \\ FeatureClass: {1}".format(dataset, fc))
                     try:
                         fields = arcpy.ListFields(fc)
                         str_output = ""
@@ -151,15 +160,18 @@ def export_all_domains(geodatabase, workspace=None):
     """Output all the domains in a geodatabase
     to tables in a workspace.
 
-    :param geodatabase {String}:
+    :param geodatabase {String|pathlike|object}:
         Path or reference to input geodatabase.
     
-    :param workspace {String}: Optional
+    :param workspace {String|pathlike|object}: Optional
         Path to output folder or geodatabase. Defaults to input geodatabase.
     """
     try:
+        geodatabase = _ensure_valid_path(_resolve_dataset_path(geodatabase, arg_name="geodatabase"))
         if not workspace:
             workspace = geodatabase
+        else:
+            workspace = _resolve_dataset_path(workspace, arg_name="workspace")
         domains = arcpy.da.ListDomains(geodatabase)
         for domain in domains:
             dname = arcpy.ValidateTableName(domain.name + '_domain', workspace)
@@ -179,13 +191,20 @@ def export_all_domains(geodatabase, workspace=None):
 def import_tables_as_domains(tables, geodatabase):
     """import tables as domains into geodatabase. Expects fields 'codedValues' and 'description'
     
-    :param tables {string}
-        path or array of paths of input tables containing domain data
+    :param tables {string|pathlike|object|array}
+        table path/object or array of table paths/objects containing domain data
     
-    :param geodatabase
-        Path or reference to geodatabase."""
+    :param geodatabase {String|pathlike|object}
+        Path or reference to geodatabase.
+
+    Notes:
+        Single string inputs are treated as a single table path (not iterated per character).
+        Invalid paths raise ValueError("invalid path").
+    """
     try:
-        for table in tables:
+        geodatabase = _ensure_valid_path(_resolve_dataset_path(geodatabase, arg_name="geodatabase"))
+        for table in _normalize_to_sequence(tables):
+            table = _ensure_valid_path(_resolve_dataset_path(table, arg_name="tables"))
             desc = arcpy.Describe(table)
             dname = desc.name.replace("_domain", "")
             arcpy.TableToDomain_management(table, "codedValues", "description", geodatabase, dname)

arc_utils-1.3/arc_utils/output.py

@@ -0,0 +1,111 @@
+# -*- coding: utf-8 -*-
+"""output related utilities
+"""
+import arcpy
+import os
+
+def output_msg(msg, severity=0):
+    """Output msg to print and/or to Arc. Useful to include in a tool
+    that can be run in Python or in ArcGIS
+
+    msg{String}:
+        message to output.
+
+    severity(integer):
+        severity = 0 (none), 1 (warning), 2 (error)
+    usage:
+        output_msg("message")
+
+    function from http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//00150000000p000000.htm
+    """
+
+    # Adds a Message (in case this is run as a tool)
+    # and also prints the message to the screen (standard output)
+    #
+    print(msg)
+
+    # Split the message on \n first, so that if it's multiple lines,
+    #  a GPMessage will be added for each line
+    try:
+        for string in msg.split('\n'):
+            # Add appropriate geoprocessing message
+            #
+            if severity == 0:
+                arcpy.AddMessage(string)
+            elif severity == 1:
+                arcpy.AddWarning(string)
+            elif severity == 2:
+                arcpy.AddError(string)
+    except:
+        pass
+
+
+def get_valid_output_path(path, return_folder_only=True, make_dir=True, fallback_to_user_folder=True):
+    """ return a valid path or empty string if not valid.
+    If return_folder_only is True (default) and a gdb is passed as path,
+       will return the folder containing gdb.
+    If make_dir is True (default), path will be created if it doesn't exist..
+    If fallback_to_user_folder is True (default), will fallback to userprofile\documents folder
+    path {String}:
+        filepath
+    return_folder_only {Boolean}:
+        returned path must be a folder, not a .gdb
+    make_dir {Boolean}:
+        make the directory if not exists
+    fallback_to_user_folder {Boolean}:
+        if path not valid, fallback to userprofile\documents folder (if available)
+    :return path or empty string
+    """
+    def _fallback_user_folder():
+        if not fallback_to_user_folder:
+            return ''
+        user_profile = os.environ.get('USERPROFILE') or os.path.expanduser('~')
+        if not user_profile:
+            return ''
+        docs_dir = os.path.join(user_profile, 'Documents')
+        if os.path.isdir(docs_dir):
+            return docs_dir
+        if os.path.isdir(user_profile):
+            return user_profile
+        return ''
+
+    try:
+        path = os.fspath(path)
+    except (TypeError, ValueError):
+        return _fallback_user_folder()
+
+    if not path:
+        return _fallback_user_folder()
+
+    path = os.path.abspath(os.path.expanduser(path))
+    report_dir = path
+
+    if os.path.isdir(path):
+        if return_folder_only and path.lower().endswith('.gdb'):
+            try:
+                report_dir = arcpy.Describe(path).Path
+            except Exception:
+                return _fallback_user_folder()
+    elif make_dir:
+        try:
+            os.makedirs(path)
+            report_dir = path
+        except OSError:
+            return _fallback_user_folder()
+    else:
+        return _fallback_user_folder()
+
+    if not os.path.isdir(report_dir):
+        return _fallback_user_folder()
+
+    return report_dir
+
+
+def output_to_file(data, path, filename):
+    """send result string to file"""
+    path = get_valid_output_path(path)
+    if not path:
+        raise ValueError("invalid output path")
+    output_file = os.path.join(path, filename)
+    with open(output_file, "w") as output:
+        output.write('{}'.format(data))