feat(ref): support fetching GENCODE GTFs and FASTAs (#73)

docs/src/en/ref.md

@@ -2,13 +2,14 @@
 
 > Python arguments are equivalent to long-option arguments (`--arg`), unless otherwise specified. Flags are True/False arguments in Python. The manual for any gget tool can be called from the command-line using the `-h` `--help` flag.  
 # gget ref 📖
-Fetch download links and metadata for [Ensembl](https://www.ensembl.org/) reference genomes.  
+Fetch download links and metadata for [Ensembl](https://www.ensembl.org/) and [GENCODE](https://www.gencodegenes.org/) reference genomes.  
 Return format: dictionary/JSON.
 
 **Positional argument**  
 `species`  
 Species for which the FTPs will be fetched in the format genus_species, e.g. homo_sapiens.  
 Supports all available vertebrate and invertebrate (plants, fungi, protists, and invertebrate metazoa) genomes from Ensembl, except bacteria.  
+For `source=gencode`, only human ('human'/'homo_sapiens') and mouse ('mouse'/'mus_musculus') are supported.  
 Note: Not required when using flags `--list_species` or `--list_iv_species`.  
 Supported shortcuts: 'human', 'mouse', 'human_grch37' (accesses the GRCh37 genome assembly)
 
@@ -22,9 +23,14 @@ Possible entries are one or a combination (as comma-separated list) of the follo
 'cds' - Returns the coding sequences corresponding to Ensembl genes. (Does not contain UTR or intronic sequence.)  
 'cdrna' - Returns transcript sequences corresponding to non-coding RNA genes (ncRNA).  
 'pep' - Returns the protein translations of Ensembl genes.  
+Note: `source=gencode` does not provide 'cds'; with GENCODE, 'cdna' returns transcript sequences and 'ncrna' returns long non-coding RNA transcript sequences.  
 
 `-r` `--release`  
-Defines the Ensembl release number from which the files are fetched, e.g. 104. Default: latest Ensembl release.  
+Defines the release number from which the files are fetched, e.g. 104. Default: latest release.  
+For `source=gencode`, this is the GENCODE release number (e.g. 46); the mouse 'M' prefix is added automatically.  
+
+`-src` `--source`  
+Reference database to fetch from: 'ensembl' (default) or 'gencode'. GENCODE provides human and mouse references only.  
 
 `-od` `--out_dir`  
 Path to the directory where the FTPs will be saved, e.g. path/to/directory/. Default: Current working directory.
@@ -40,6 +46,9 @@ Lists all available vertebrate species. (Python: combine with `species=None`.)
 `-liv` `--list_iv_species`  
 Lists all available invertebrate species. (Python: combine with `species=None`.)  
 
+`-lf` `--list_files`  
+Only for `--source gencode`. Lists every file in the GENCODE release directory for the given species (beyond the curated `-w`/`--which` set), e.g. GFF3, basic/comprehensive annotation, `pc_transcripts`, and metadata files. Combine with `--release` to target a specific GENCODE release.  
+
 `-ftp` `--ftp`  
 Returns only the requested FTP links.  
 
@@ -98,6 +107,31 @@ gget.ref(species=None, list_species=True, release=103)
 
 <br/><br/>
 
+**Fetch human reference GTF and genome FASTA from GENCODE (release 46):**  
+```bash
+gget ref -w gtf,dna -r 46 --source gencode human
+```
+```python
+# Python
+gget.ref("human", which=["gtf", "dna"], release=46, source="gencode")
+```
+&rarr; Returns a JSON with the GENCODE v46 human GTF and genome FASTA FTPs and their metadata.  
+(GENCODE is available for human and mouse only. Omit `--release` to use the latest GENCODE release.)
+
+<br/><br/>
+
+**List every file in a GENCODE release directory (to fetch files beyond the `which` set):**  
+```bash
+gget ref --list_files -r 46 --source gencode human
+```
+```python
+# Python
+gget.ref("human", list_files=True, release=46, source="gencode")
+```
+&rarr; Returns a JSON keyed by filename with every file in the GENCODE v46 human release directory (GFF3, basic/comprehensive annotation, `pc_transcripts`, metadata, etc.) and its FTP link, date, and size. Use this to reach GENCODE-specific files that `which` does not expose.
+
+<br/><br/>
+
 **Use `gget ref` in combination with [kallisto | bustools](https://www.kallistobus.tools/kb_usage/kb_ref/) to build a reference index:**
 ```bash
 kb ref \

docs/src/en/updates.md

@@ -5,6 +5,10 @@
 #### *gget* officially became part of [*scverse*](https://scverse.org/) on June 9, 2026. 🥳🥳🥳
 
 **Version ≥ 0.30.9** (XXX XX, 2026):  
+- [`gget ref`](ref.md): Added support for fetching reference GTFs and FASTAs from [GENCODE](https://www.gencodegenes.org/).
+  - New `source` argument (command line: `--source`/`-src`) selects the reference database: `"ensembl"` (default, unchanged behavior) or `"gencode"` (human and mouse only).
+  - With `source="gencode"`, the `release` argument is the GENCODE release number (e.g. `46`; the mouse `M` prefix is added automatically) and defaults to the latest release. `which` supports `gtf`, `dna` (primary assembly genome), `cdna` (transcript sequences), `ncrna` (long non-coding RNA transcripts), and `pep` (protein translations); GENCODE does not provide `cds`.
+  - New `list_files` flag (command line: `--list_files`/`-lf`), only for `source="gencode"`, lists every file in a GENCODE release directory (keyed by filename) so GENCODE-specific files beyond the `which` set — GFF3, basic/comprehensive annotation, `pc_transcripts`, metadata, etc. — can be fetched.
 
 **Version ≥ 0.30.8** (Jun 28, 2026):  
 - [`gget g2p`](g2p.md): Either `gene` or `--uniprot_id` is now sufficient — whichever is missing is resolved via UniProt and cached. Gene→UniProt picks the canonical reviewed human Swiss-Prot entry; the resolution and its limitations are logged. The canonical pair is **always** prepended to the result as `gene_name` / `uniprot_id` columns (and stored on `df.attrs`), so the output schema is invariant regardless of input mode. Existing call sites continue to work.

docs/src/es/ref.md

@@ -2,14 +2,15 @@
 
 > Parámetros de Python són iguales a los parámetros largos (`--parámetro`) de Terminal, si no especificado de otra manera. Banderas son parámetros de verdadero o falso (True/False) en Python. El manuál para cualquier modulo de gget se puede llamar desde la Terminal con la bandera `-h` `--help`.  
 # gget ref 📖
-Obtenga enlaces de descarga y metadatos para los genomas de referencia de [Ensembl](https://www.ensembl.org/).  
+Obtenga enlaces de descarga y metadatos para los genomas de referencia de [Ensembl](https://www.ensembl.org/) y [GENCODE](https://www.gencodegenes.org/).  
 Regresa: Resultados en formato JSON.  
 
 **Parámetro posicional**  
 `species`  
 La especie por la cual que se buscará los FTP en el formato género_especies, p. ej. homo_sapiens.  
 Nota: No se requiere cuando se llama a la bandera `--list_species`.  
 Accesos directos: 'human', 'mouse', 'human_grch37' (accede al ensamblaje del genoma GRCh37)  
+Para `source=gencode`, solo se admiten humano ('human'/'homo_sapiens') y ratón ('mouse'/'mus_musculus').  
 
 **Parámetros optionales**  
 `-w` `--which`  
@@ -21,9 +22,14 @@ Las entradas posibles son uno solo o una combinación de las siguientes (como li
 'cds' - Regresa las secuencias codificantes correspondientes a los genes Ensembl. (No contiene UTR ni secuencia intrónica).  
 'cdrna' - Regresa secuencias de transcripción correspondientes a genes de ARN no codificantes (ncRNA).  
 'pep' - Regresa las traducciones de proteínas de los genes Ensembl.  
+Nota: `source=gencode` no proporciona 'cds'; con GENCODE, 'cdna' regresa secuencias de transcripción y 'ncrna' regresa secuencias de transcripción de ARN largo no codificante.  
 
 `-r` `--release`  
-Define el número de versión de Ensembl desde el que se obtienen los archivos, p. ej. 104. Default: latest Ensembl release.  
+Define el número de versión desde el que se obtienen los archivos, p. ej. 104. Por defecto: la última versión.  
+Para `source=gencode`, este es el número de versión de GENCODE (p. ej. 46); el prefijo 'M' para ratón se añade automáticamente.  
+
+`-src` `--source`  
+Base de datos de referencia de la que obtener los archivos: 'ensembl' (por defecto) o 'gencode'. GENCODE proporciona referencias solo para humano y ratón.  
 
 `-od` `--out_dir`  
 Ruta al directorio donde se guardarán los archivos FTP, p. ruta/al/directorio/. Por defecto: directorio de trabajo actual.  
@@ -36,6 +42,9 @@ Para Python, usa `save=True` para guardar los resultados en el directorio de tra
 `-l` `--list_species`  
 Enumera todas las especies disponibles. (Para Python: combina con `species=None`.)  
 
+`-lf` `--list_files`  
+Solo para `--source gencode`. Enumera todos los archivos del directorio de la versión de GENCODE para la especie indicada (más allá del conjunto seleccionado por `-w`/`--which`), p. ej. GFF3, anotación básica/completa, `pc_transcripts` y archivos de metadatos. Combínalo con `--release` para apuntar a una versión específica de GENCODE.  
+
 `-ftp` `--ftp`  
 Regresa solo los enlaces FTP solicitados.  
 
@@ -68,6 +77,31 @@ gget.ref(species=None, list_species=True, release=103)
 
 <br/><br/>
 
+**Obtenga el GTF de referencia humano y el FASTA del genoma desde GENCODE (versión 46):**  
+```bash
+gget ref -w gtf,dna -r 46 --source gencode human
+```
+```python
+# Python
+gget.ref("human", which=["gtf", "dna"], release=46, source="gencode")
+```
+&rarr; Regresa un JSON con los FTP del GTF humano y el FASTA del genoma de GENCODE v46 y sus metadatos.  
+(GENCODE está disponible solo para humano y ratón. Omita `--release` para usar la última versión de GENCODE).
+
+<br/><br/>
+
+**Enumere todos los archivos de un directorio de versión de GENCODE (para obtener archivos más allá del conjunto `which`):**  
+```bash
+gget ref --list_files -r 46 --source gencode human
+```
+```python
+# Python
+gget.ref("human", list_files=True, release=46, source="gencode")
+```
+&rarr; Regresa un JSON indexado por nombre de archivo con todos los archivos del directorio de la versión 46 humana de GENCODE (GFF3, anotación básica/completa, `pc_transcripts`, metadatos, etc.) junto con su enlace FTP, fecha y tamaño. Úselo para alcanzar archivos específicos de GENCODE que `which` no expone.
+
+<br/><br/>
+
 **Obtenga la referencia del genoma para una especie específica:**  
 ```bash
 gget ref -w gtf,dna homo_sapiens

docs/src/es/updates.md

@@ -4,6 +4,12 @@
 
 #### *gget* se unió oficialmente a *scverse* el 9 de junio de 2026. 🥳🥳🥳
 
+**Versión ≥ 0.30.9** (XXX XX, 2026):  
+- [`gget ref`](ref.md): Se añadió soporte para obtener GTFs y FASTAs de referencia desde [GENCODE](https://www.gencodegenes.org/).
+  - Nuevo argumento `source` (línea de comandos: `--source`/`-src`) que selecciona la base de datos de referencia: `"ensembl"` (por defecto, comportamiento sin cambios) o `"gencode"` (solo humano y ratón).
+  - Con `source="gencode"`, el argumento `release` es el número de versión de GENCODE (p. ej. `46`; el prefijo `M` para ratón se añade automáticamente) y por defecto usa la última versión. `which` admite `gtf`, `dna` (genoma del ensamblaje primario), `cdna` (secuencias de transcripción), `ncrna` (transcripciones de ARN largo no codificante) y `pep` (traducciones de proteínas); GENCODE no proporciona `cds`.
+  - Nueva bandera `list_files` (línea de comandos: `--list_files`/`-lf`), solo para `source="gencode"`, enumera todos los archivos de un directorio de versión de GENCODE (indexados por nombre de archivo) para poder obtener archivos específicos de GENCODE más allá del conjunto `which` — GFF3, anotación básica/completa, `pc_transcripts`, metadatos, etc.
+
 **Versión ≥ 0.30.8** (28 de junio de 2026):  
 - [`gget g2p`](g2p.md): Ahora es suficiente con `gene` o `--uniprot_id` — el que falte se resuelve a través de UniProt y se almacena en caché. Gene→UniProt selecciona la entrada canónica revisada humana de Swiss-Prot; la resolución y sus limitaciones se registran. El par canónico **siempre** se añade al inicio del resultado como columnas `gene_name` / `uniprot_id` (y se almacena en `df.attrs`), por lo que el esquema de salida es invariante independientemente del modo de entrada. Los sitios de llamada existentes siguen funcionando.
   - Nuevo filtro `residues=` (Python: int / list / range / set; CLI `--residues 100,200,300` o `100-200`) restringe `features` / `alignment` a posiciones específicas del lado del cliente.

gget/constants.py

@@ -14,6 +14,9 @@
 # Non-vertebrate server
 ENSEMBL_FTP_URL_NV = "http://ftp.ensemblgenomes.org/pub/"
 
+# GENCODE FTP root for gget ref (human and mouse reference GTFs/FASTAs)
+GENCODE_FTP_URL = "https://ftp.ebi.ac.uk/pub/databases/gencode/"
+
 # NCBI URL for gget info
 NCBI_URL = "https://www.ncbi.nlm.nih.gov"