hyper-py-photometry 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

hyper_py/__init__.py

@@ -1 +1,21 @@
-from hyper_py.hyper import start_hyper
+"""
+Hyper-Py package initializer.
+
+This file defines the public API and version metadata.
+It does not run the application automatically; use
+either `python -m hyper_py` or the console script entry point.
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+from .hyper import start_hyper
+
+try:
+    __version__ = version("hyper-py-photometry")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+__all__ = [
+    "start_hyper",
+    "__version__",
+]

hyper_py/__main__.py

@@ -0,0 +1,7 @@
+# Allows: python -m hyper_py [optional /path/to/config.yaml]
+# This delegates to the same CLI logic used by the console_script entry point.
+
+from .run_hyper import main
+
+if __name__ == "__main__":
+    main()

hyper_py/hyper.py

@@ -22,7 +22,7 @@ def start_hyper(cfg_path):
     # === Load config ===
     os.chdir(os.path.dirname(__file__))
 
-    config_path = cfg_path if not None else "config.yaml"
+    config_path = cfg_path if not None else "hyper_config.yaml"
     
     if not os.path.exists(config_path):
         raise FileNotFoundError(f"Config file not found: {config_path}")

hyper_py/run_hyper.py

@@ -1,45 +1,154 @@
 import sys
 import os
-import shutil
 import warnings
-import yaml
+import shutil
+import platform
 from pathlib import Path
 
-sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
-
-# Block warnings
+# Silence some known irrelevant warnings
 warnings.filterwarnings("ignore", message="Using UFloat objects with std_dev==0 may give unexpected results.")
 warnings.filterwarnings("ignore", message=".*Set OBSGEO-L to.*")
 warnings.filterwarnings("ignore", message=".*Wrapping comment lines > 78 characters.*")
-warnings.filterwarnings("ignore", message=".*more axes \(4\) than the image it is associated with \(2\).*")
+warnings.filterwarnings("ignore", message=".*more axes \\(4\\) than the image it is associated with \\(2\\).*")
 warnings.filterwarnings("ignore", message=".*Set MJD-OBS to.*")
 
+# Import the main entry point of the package
 from hyper_py.hyper import start_hyper
 
-def update_dir_root(default_config, config_path, new_dir_root):
-    """Create a new config.yaml in the specified directory with updated dir_root."""
-    default_config = Path(default_config)
-    config_path = Path(config_path)      
-    cfg = yaml.safe_load(default_config.read_text(encoding="utf-8")) or {}
-    cfg['paths']['output']['dir_root'] = str(Path(new_dir_root, "output"))
-    config_path.write_text(yaml.safe_dump(cfg, sort_keys=False), encoding="utf-8")
-
-def main():
-    config_path = sys.argv[1] if len(sys.argv) > 1 else "config.yaml"
-    if not os.path.exists(config_path):
-        default_config = os.path.join(os.path.dirname(__file__), "config.yaml")
-        if not os.path.exists(default_config):
-            print("Error: default config.yaml not found.")
-            sys.exit(1)
-
-        config_path = os.path.join(os.getcwd(), "config.yaml")
-
-        update_dir_root(default_config, config_path, os.getcwd())
-        print(f"⚠️  New config.yaml created in {config_path}")
-        print("⚠️  Please edit the configuration file and set the correct parameters and paths before running again.")
+# importlib.resources for packaged data (fallback to importlib_resources on older Python)
+try:
+    from importlib.resources import files as ir_files
+except Exception:  # Python <3.9
+    from importlib_resources import files as ir_files  # type: ignore
+
+# Try ruamel.yaml for comment-preserving roundtrips
+try:
+    from ruamel.yaml import YAML  # type: ignore
+    _HAS_RUAMEL = True
+except Exception:
+    _HAS_RUAMEL = False
+
+_PKG = "hyper_py"  # top-level package name
+_CONFIG_FILENAME = "hyper_config.yaml"  # custom config filename
+
+
+def _user_config_path() -> Path:
+    """Return the user-level config path depending on the operating system."""
+    if platform.system() == "Windows":
+        base = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+        return base / "HyperPy" / _CONFIG_FILENAME
+    base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return base / "hyper-py" / _CONFIG_FILENAME
+
+
+def _load_default_template_path() -> Path:
+    """
+    Locate the packaged default config template.
+    Fallback to local files when running directly from src (dev mode).
+    """
+    try:
+        res = ir_files(_PKG).joinpath("assets/default_config.yaml")
+        if res and os.path.isfile(str(res)):
+            return Path(str(res))
+    except Exception:
+        pass
+
+    # Fallbacks for development mode
+    here = Path(__file__).parent
+    for cand in (
+        here / "assets" / "default_config.yaml",
+        here / "config.yaml",
+        here.parent / "config.yaml",
+    ):
+        if cand.is_file():
+            return cand
+
+    print("Error: default config template not found in package or src.")
+    sys.exit(1)
+
+
+def _ensure_parent(p: Path) -> None:
+    """Ensure the parent directory exists."""
+    p.parent.mkdir(parents=True, exist_ok=True)
+
+
+def _copy_template_to(dest: Path) -> None:
+    """Copy the default template into the destination config file."""
+    src = _load_default_template_path()
+    _ensure_parent(dest)
+    with src.open("rb") as s, dest.open("wb") as d:
+        shutil.copyfileobj(s, d)
+
+
+def _resolve_config_path(argv: list[str]) -> Path:
+    """Resolve the path of the configuration file from CLI args or default locations."""
+    # 1) CLI argument
+    if len(argv) > 1:
+        return Path(argv[1]).expanduser().resolve()
+    # 2) config file in the current working directory
+    cwd_cfg = Path.cwd() / _CONFIG_FILENAME
+    if cwd_cfg.is_file():
+        return cwd_cfg
+    # 3) user config path
+    ucfg = _user_config_path()
+    if ucfg.is_file():
+        return ucfg
+    # 4) if nothing found, suggest CWD/hyper_config.yaml as creation target
+    return cwd_cfg
+
+
+def _update_dir_root_preserving_comments(config_path: Path, new_dir_root: Path) -> None:
+    """
+    Update paths.output.dir_root preserving comments and formatting using ruamel.yaml.
+    If ruamel.yaml is not available, do nothing (keep template intact and let the user edit).
+    """
+    if not _HAS_RUAMEL:
+        print("Note: ruamel.yaml not installed; left config comments intact. "
+              "Please edit 'paths.output.dir_root' manually in hyper_config.yaml.")
+        return
+
+    yaml = YAML()
+    yaml.preserve_quotes = True
+    yaml.indent(mapping=2, sequence=4, offset=2)
+
+    with config_path.open("r", encoding="utf-8") as f:
+        data = yaml.load(f) or {}
+
+    # Ensure nested mapping exists without destroying comments
+    paths = data.get("paths")
+    if paths is None:
+        from ruamel.yaml.comments import CommentedMap  # type: ignore
+        paths = CommentedMap()
+        data["paths"] = paths
+
+    output = paths.get("output")
+    if output is None:
+        from ruamel.yaml.comments import CommentedMap  # type: ignore
+        output = CommentedMap()
+        paths["output"] = output
+
+    output["dir_root"] = str(new_dir_root / "output")
+
+    with config_path.open("w", encoding="utf-8") as f:
+        yaml.dump(data, f)
+
+
+def main() -> None:
+    """Main entry point for CLI execution."""
+    cfg_path = _resolve_config_path(sys.argv)
+
+    if not cfg_path.exists():
+        # Create new hyper_config.yaml from packaged template
+        _copy_template_to(cfg_path)
+        # Update dir_root while preserving comments (if ruamel.yaml is available)
+        _update_dir_root_preserving_comments(cfg_path, Path.cwd())
+        print(f"⚠️  New {_CONFIG_FILENAME} created at: {cfg_path}")
+        print("⚠️  Please edit it and run the command again.")
         sys.exit(0)
 
-    start_hyper(config_path)
+    # Run the real application
+    start_hyper(str(cfg_path))
+
 
 if __name__ == "__main__":
     main()

{hyper_py_photometry-0.1.2.dist-info → hyper_py_photometry-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyper-py-photometry
-Version: 0.1.2
+Version: 0.1.4
 Summary: HYPER: Hybrid Photometry Photometry and Extraction Routine
 Author-email: Alessio Traficante <alessio.traficante@inaf.it>
 Project-URL: Homepage, https://github.com/alessio-traficante/hyper-py
@@ -15,6 +15,7 @@ Requires-Dist: scipy
 Requires-Dist: lmfit
 Requires-Dist: matplotlib
 Requires-Dist: scikit-learn<1.6,>=1.4
+Requires-Dist: ruamel.yaml>=0.18
 Dynamic: license-file
 
 # 💫 `Hyper-py`: Hybrid Photometry Photometry and Extraction Routine in Python
@@ -61,7 +62,7 @@ Hyper-py now supports **parallel execution** over multiple maps or datacube slic
 - Maintain **individual log files** for each map
 - Merge the final outputs (tables and diagnostics) into a single, combined summary
 
-To enable parallelism, set the following parameters in your `config.yaml` file under the `control` section:
+To enable parallelism, set the following parameters in your `hyper_config.yaml` file under the `control` section:
 
 ```yaml
 control:
@@ -72,30 +73,16 @@ control:
 If `parallel_maps` is set to `false`, the pipeline will run in serial mode.
 
 
+## 🛠️ Installation
+You can install and use `Hyper-py` in two different ways, depending on your needs:
 
-## 🚀 Prerequisites
-
-Before using `Hyper-py`, make sure you have all the necessary Python dependencies installed. The following core libraries are required:
-	•	astropy
-	•	photutils
-	•	matplotlib
-	•	lmfit
-  •	pyyaml
-  •	numpy
-  •	scipy
-  •	scikit-learn>=1.4,<1.6
-	
-This will install the necessary packages using `pip`:
-
+### Option 1: Install via `pip` (for direct usage)
+Install via PyPI:
 ```bash
-astropy photutils matplotlib lmfit
+pip install hyper-py-photometry
 ```
 
-
-## 🛠️ Installation
-You can install and use `Hyper-py` in two different ways, depending on your needs:
-
-### Option 1: Use the Source Code (for development or integration)
+### Option 2: Use the Source Code (for development or integration)
 
 If you want to modify, extend, or integrate `Hyper-py` in your own projects:
 
@@ -115,27 +102,71 @@ export PYTHONPATH=$(pwd)/src
 import sys
 sys.path.insert(0, "/absolute/path/to/hyper_py/src")
 ```
-### Option 2: Install via `pip` (for direct usage)
-Install via PyPI:
+
+
+## ✅ Requirements
+
+Before using `Hyper-py`, make sure you have all the necessary Python dependencies installed. 
+
+If you have installed `Hyper-py` via pip, all the requirements are automatically installed.
+Otherwise, you can use the `requirements.txt` file, this will install the necessary packages using `pip`::
 ```bash
-pip install hyper-py-photometry
+pip install -r requirements.txt
 ```
 
 
-## 🎯 Usage
+## 📄 Configuration File
+
+
+`Hyper-py` requires a configuration file named **`hyper_config.yaml`** in order to run.  
+
+>The first time you run `Hyper-py` a new hyper_config.yaml will be created automatically in the CWD, then you must setup all paths and paramenters.<br>
+>If you already have a configuration file ready or you have moved the new configuration file to a different folder, provide the path as argument.
+
+If no path is provided, the application will look for it in this order:  
+1. Path passed as CLI argument  
+2. `hyper_config.yaml` in the current working directory (CWD)  
+3. User configuration directory  
+    - Linux/macOS: `~/.config/hyper-py/hyper_config.yaml`  
+    - Windows: `%APPDATA%\HyperPy\hyper_config.yaml`  
+4. If not found, a new `hyper_config.yaml` will be created automatically in the CWD, copied from the package template (`assets/default_config.yaml`).  
 
-You can use `Hyper-py` either by importing and running it directly from Python, or via command line.
 > [!IMPORTANT]  
->  `Hyper-py` needs a configuration file in order to run. If no configuration file path is provided, the default file located in the `src/` folder will be used.
+> <span style="font-weight:bold;">Before running the pipeline, you <span style="color:red; font-weight:bold;">must</span> edit **`hyper_config.yaml`** and set the correct parameters and paths.</span> 
+
+
+### Configuration file lookup order
+
+| Priority | Location                                   | Description                                                                 |
+|----------|--------------------------------------------|-----------------------------------------------------------------------------|
+| 1        | CLI argument                               | Path explicitly provided by the user, e.g. `hyper-py /path/to/hyper_config.yaml`. |
+| 2        | Current Working Directory (CWD)            | Looks for `./hyper_config.yaml` in the folder where the command is executed. |
+| 3        | User configuration directory               | - **Linux/macOS:** `~/.config/hyper-py/hyper_config.yaml`<br> - **Windows:** `%APPDATA%\HyperPy\hyper_config.yaml` |
+| 4        | Auto-generated in CWD if none is found     | A new `hyper_config.yaml` is created, copied from the package template (`assets/default_config.yaml`). |
+
+### 💡 Tips & Tricks
+
+- **Use different configs**  
+  You can maintain multiple configuration files (e.g., `hyper_config.dev.yaml` and `hyper_config.prod.yaml`) and choose which one to run. 
+  <br>Eg. If you have installed via pip:
+  ```bash
+  hyper-py ./hyper_config.dev.yaml
+  hyper-py ./hyper_config.prod.yaml
+  ```
+
+
+## 🚀 Usage
+
+You can use `Hyper-py` either by importing and running it directly from Python, or via command line.
 
 ### 1. From Python
 
-Import and run the `start_hyper` function, passing the path to your YAML configuration file.
+Import and run the `run_hyper` function, passing the path to your YAML configuration file.
 
 ```python
 from hyper_py import run_hyper
 
-run_hyper("path/to/config.yaml")
+run_hyper("path/to/hyper_config.yaml")
 ```
 This is the recommended approach if you want to integrate `Hyper-py` into a larger Python application or workflow.
 
@@ -145,7 +176,7 @@ I) Using the source code:
 
 You can execute the tool from the terminal:
 ```bash
-python -m hyper_py path/to/config.yaml
+python -m hyper_py path/to/hyper_config.yaml
 ```
 This runs the main process using the configuration file specified.
 
@@ -153,18 +184,18 @@ II) If installed via pip:
 
 Once the .whl package is installed (e.g., via pip install hyper_py-X.X.X-py3-none-any.whl), you can run it directly:
 ```bash
-hyper_py path/to/config.yaml
+hyper_py path/to/hyper_config.yaml
 ```
 OR
 ```bash
-hyper-py path/to/config.yaml
+hyper-py path/to/hyper_config.yaml
 ```
 OR
 ```bash
-hyper path/to/config.yaml
+hyper path/to/hyper_config.yaml
 ```
 
-## Using the Source Code in Visual Studio Code
+## 💻 Using the Source Code in Visual Studio Code
 To run or debug the source code using Visual Studio Code:
 ### 1. Open the project
 - Open the project folder in VS Code.
@@ -193,7 +224,7 @@ Optional: You can add this to `.vscode/launch.json` for convenience:
       "request": "launch",
       "program": "${workspaceFolder}/src/hyper_py/run_hyper.py",
       "console": "integratedTerminal",
-      "args": ["path/to/config.yaml"], // Specify a different config file
+      "args": ["path/to/hyper_config.yaml"],
     }
   ]
 }
@@ -202,9 +233,9 @@ Optional: You can add this to `.vscode/launch.json` for convenience:
 <br/><br/>
 
 
-## ⚙️ Configuration File Reference (`config.yaml`)
+## ⚙️ Configuration File Reference (`hyper_config.yaml`)
 
-The `config.yaml` file controls all aspects of the Hyper-py pipeline. Below is a detailed explanation of every entry, including its purpose, accepted values, default, and type.
+The `hyper_config.yaml` file controls all aspects of the Hyper-py pipeline. Below is a detailed explanation of every entry, including its purpose, accepted values, default, and type.
 
 ### File Paths
 
@@ -354,7 +385,7 @@ The `config.yaml` file controls all aspects of the Hyper-py pipeline. Below is a
 ---
 
 **Tip:**  
-All entries can be customized in your `config.yaml`. If an entry is omitted, the default value will be used.
+All entries can be customized in your `hyper_config.yaml`. If an entry is omitted, the default value will be used.
 
 
 

{hyper_py_photometry-0.1.2.dist-info → hyper_py_photometry-0.1.4.dist-info}/RECORD

@@ -1,8 +1,8 @@
-hyper_py/__init__.py,sha256=BXdlhYa5Z_wBk1fo-L50xblSZF-vepSqz9kXWkewCdw,38
+hyper_py/__init__.py,sha256=11pucLbbhjgiTjT0_HYsgSXqtRje5XtbbI-blW-DZ9g,469
+hyper_py/__main__.py,sha256=VEzRWxxjj8Jja0FY5TiqDWaYkqYsFhHirbAK2gxRFTg,208
 hyper_py/bkg_multigauss.py,sha256=SuVlEMkPOccqOuATCaoEBU_WpQARAlHJa2qwAkglHII,22778
 hyper_py/bkg_single.py,sha256=stGiZIAFabOW3QHxakA2pJ0__HjgyvcPD2TnB3ARbZc,20269
 hyper_py/config.py,sha256=evafwkxft8YK4vbAjOlBdB796gYd4zNnHt8wJbOabPs,1473
-hyper_py/config.yaml,sha256=64DJtYhwHX6XkbOyuGMmn51WwjK0uJpNafRe8CwkkO4,10616
 hyper_py/create_background_slices.py,sha256=VjR_cwRYWFFmEkpcJ8fXcnc6oSAbtY2DPjGWvbs5ecc,6090
 hyper_py/data_output.py,sha256=VKtYPBdez3N2imZFE4Ugwa9JmFFUC28J7XdVFmqhGYE,5532
 hyper_py/detection.py,sha256=txnEjnBBL0aX_Fz9Fa7ks_6AKtgbCBs15WHgF1ZBX9s,4738
@@ -10,18 +10,19 @@ hyper_py/extract_cubes.py,sha256=hmfp5MoA5HKOwEduXqmV8uahfBbL479Qr5cC84zT7z0,164
 hyper_py/fitting.py,sha256=MTw9Yt4LYAybVXM5uI_IgQiT5Maiz_W9EyWqHLEXVkY,26010
 hyper_py/gaussfit.py,sha256=t_LlKd5hJZB1K2fGnZsd6v-q2h-M5XCW214FYjDCFOU,22833
 hyper_py/groups.py,sha256=Q2xQ4MqYR-sRpRhNtayMqTVPMi2rm0ie34mmCDwTbNY,2303
-hyper_py/hyper.py,sha256=qDjE-xzP1D-4FdFauaV82ZZp0EiHNwLz1wOb1IAmNGw,6012
+hyper_py/hyper.py,sha256=574EnlwCXTesCkOK_L3dMMnIo8uU4G1RWj_Tgaz2F7c,6018
 hyper_py/logger.py,sha256=He18tjVOvG7_OVGY6262wj30HExoEa7vCFO6WziHSFk,2864
 hyper_py/map_io.py,sha256=QHYsMFOA1Jzmx-ou_CFHAdRLXl00ynf2dYK8PZGh2CQ,2363
 hyper_py/paths_io.py,sha256=fUl0GjwUZLEDXZAUlLK88DB6mBQ_il7fIa-vvKVUxRI,3770
 hyper_py/photometry.py,sha256=4oCRZy8FVjV9BZL5f85LlcNnXuNq0wgtGAm8_cL5f9w,3869
-hyper_py/run_hyper.py,sha256=nQwMvwggvno6PYxl06wCBXF-Rm1oftI4OzS-qNa-WbA,1873
+hyper_py/run_hyper.py,sha256=ZQYEuvU_SFsmLn7g61a169dGS3jL-NhHHdi7jckqQ0s,5220
 hyper_py/single_map.py,sha256=YXlMiixK-CLfiFjmLiqP8RkKu6JkekEDjVi-3bQu05w,28831
 hyper_py/survey.py,sha256=ymOJk-H4Bf515OwSNFkmODKk7x3MteT6l51ylaYy9Cg,2807
 hyper_py/visualization.py,sha256=AJRuR_Y-_AaZ2NwX1w07lRABV0C2-w8QP1tSqs9_kvk,5662
-hyper_py_photometry-0.1.2.dist-info/licenses/LICENSE,sha256=aB7cqE2-X_8mxy-EmQuVMkKmP8DQA2BnQaqD5k5C5nE,584
-hyper_py_photometry-0.1.2.dist-info/METADATA,sha256=-7jNFNFdOfWTf839S2RtV5WVsH196b8q_a6EFj34gNE,32379
-hyper_py_photometry-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hyper_py_photometry-0.1.2.dist-info/entry_points.txt,sha256=0AVwuatL0ri5juy_Ccgt_9Bd4V0McpOrWSSnNX8cCzs,120
-hyper_py_photometry-0.1.2.dist-info/top_level.txt,sha256=Pw-Iuf0SQwcibLdOwx4RkmEas3I6s0Ym_D0_oUnXEr4,9
-hyper_py_photometry-0.1.2.dist-info/RECORD,,
+hyper_py/assets/default_config.yaml,sha256=64DJtYhwHX6XkbOyuGMmn51WwjK0uJpNafRe8CwkkO4,10616
+hyper_py_photometry-0.1.4.dist-info/licenses/LICENSE,sha256=aB7cqE2-X_8mxy-EmQuVMkKmP8DQA2BnQaqD5k5C5nE,584
+hyper_py_photometry-0.1.4.dist-info/METADATA,sha256=5UAU7QFSUTBQvj69foClDPRWSmeMdKSFSmprRENP-Rc,34599
+hyper_py_photometry-0.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hyper_py_photometry-0.1.4.dist-info/entry_points.txt,sha256=0AVwuatL0ri5juy_Ccgt_9Bd4V0McpOrWSSnNX8cCzs,120
+hyper_py_photometry-0.1.4.dist-info/top_level.txt,sha256=Pw-Iuf0SQwcibLdOwx4RkmEas3I6s0Ym_D0_oUnXEr4,9
+hyper_py_photometry-0.1.4.dist-info/RECORD,,